Go and WebAssembly: A Comprehensive Guide

Introduction

WebAssembly allows running compiled languages like C/C++ and Rust in the browser at near-native speeds. With WebAssembly support, Go can now produce tiny execute-anywhere binaries for the web.

In this comprehensive guide, we’ll explore the intersection of Go and WebAssembly. We’ll cover:

• What is WebAssembly and how it works
• Compiling Go to WebAssembly
• Running Go WebAssembly modules
• Passing data between JS and Go
• Debugging WebAssembly
• DOM manipulation
• Networking and concurrency
• Example use cases for Go + WebAssembly
• Performance considerations

By the end, you’ll be equipped to leverage WebAssembly to bring the performance and small binaries of Go to the browser and beyond!

Go and WebAssembly

What is WebAssembly?

WebAssembly provides a binary format that can be executed in web browsers at near-native speeds. It acts as a compilation target for languages like C/C++/Rust.

Key highlights:

• Compact binary format optimized for size and loading
• Executes with predictable performance close to native
• Integrates with JavaScript by design
• Supported in all major browsers

This allows running performance-critical code written in languages like C++ while integrating with JavaScript and web APIs.

Compiling Go to WebAssembly

The Go compiler directly supports building WebAssembly modules. To compile a Go file to WebAssembly:

GOOS=js GOARCH=wasm go build -o main.wasm main.go

This will compile main.go into a WebAssembly binary main.wasm.

We set GOOS=js and GOARCH=wasm to cross-compile for the web environment.

The resulting .wasm file contains a standalone WebAssembly module that can be run in supported hosts.

Running Go WebAssembly Modules

The compiled WebAssembly module can be run in various JavaScript environments:

Browser

Use a small launcher script to load and instantiate the module:

// main.js 

const go = new Go();

WebAssembly.instantiateStreaming(fetch('main.wasm'), go.importObject)
  .then(result => {
    go.run(result.instance);
  });

Node.js

In Node.js, the wasm-loader package helps run WebAssembly modules seemlessly:

const loader = require('@wasm-tool/wasm-loader');

(async () => {
  const go = new loader.Go(); 
  const instance = await loader.instantiate(fs.readFileSync('main.wasm'), go.importObject);
  
  go.run(instance);  
})();

This provides minimal glue code to load and call Go WebAssembly functions from JavaScript environments.

Passing Data Between JS and Go

To make WebAssembly modules truly useful, we need the ability to pass data like strings, arrays, and objects between JavaScript and WebAssembly code.

Go provides two data sharing approaches:

1. Typed arrays

Simple data types can be shared via typed arrays. For example, to sum an array of integers:

// JS side
const nums = new Int32Array([1, 2, 3]);
const sumPtr = go.sumArray(nums);
const sum = new Int32Array(go.memory.buffer)[sumPtr]; 

console.log(sum); // 6

// Go side

func sumArray(arrPtr int32) int32 {
  arr := getInt32Array(arrPtr)
  // Sum array
  return sum
}

2. JSON encoding

For rich objects, encode as JSON on one side and decode on the other:

// JS side

const obj = {msg: "Hello"};
const json = JSON.stringify(obj);

const resultPtr = go.processJSON(json);
const result = JSON.parse(go.parseResultJSON(resultPtr));

// Go side

import "encoding/json" 

func processJSON(json string) int32 {
  var obj MyData
  json.Unmarshal([]byte(json), &obj)
  // Process object
  return marshalResponse() 
}

This allows passing complex data while handling translation.

Debugging Go WebAssembly Modules

Debugging WebAssembly brings challenges like lack of source maps. Some options:

• Console output – Print to JS console from Go with console.Log
• Source maps – Generate source maps during compilation for symbolication
• Logging – Log rich structured data for analysis
• Browser DevTools – Debug WebAssembly at low level in browsers
• Node.js debugger – Node.js debugger supports WebAssembly
• GDB – Can debug WebAssembly binaries with GDB

So while raw WebAssembly debugging is still maturing, combining Go tooling and JavaScript environments provides capable options today.

Manipulating the DOM from Go

To directly interact with page content, Go code can call JavaScript DOM APIs using bindings:

// Go side

js.Global().Get("document").Call("write", "Hello World")

This will invoke document.write('Hello World') from Go!

Full DOM bindings allow building rich components.

Networking and Concurrency

Go’s primitives like goroutines and channels work nicely with JavaScript’s async capabilities:

// JS

const id = go.expensiveCalculation(args);

// Ideal spot to await result  
const result = go.calculateComplete(id);

// Go 

func expensiveCalculation(args) int {

  // Run in goroutine
  go func() {
    result := performCalculation()
    saveResult(result) 
  }()

  return resultID 
}

func calculateComplete(id int) string {
  return lookupSavedResult(id) 
}

Goroutines allow efficient concurrent work. Channels and promises can synchronize cross-language data flow.

Example Use Cases

Some examples of using Go and WebAssembly together:

• number-crunching and math-heavy code where Go shines
• image processing, encoding, and manipulation
• physics and 3D simulations with Go’s math capabilities
• CPU-bound processing like data compression/decompression
• bridging performance-critical C/C++ libraries to the web
• running Go algorithms and models in the browser
• adding powerful backend components to JavaScript frontends
• microservices compiled to WebAssembly for tiny footprints

WebAssembly unlocks new possibilities for Go in the browser and beyond!

Performance Considerations

While WebAssembly provides near-native speeds, some performance considerations apply:

• Small overhead from JavaScript ↔ WebAssembly calls
• Cost of data serialization like JSON encoding
• Single-threaded execution limits parallel performance
• Growing module size increases load time
• Avoid excessive DOM manipulations

Performance tuning across languages requires some care. Profile thoroughly against real-world scenarios.

Conclusion

This guide provided a comprehensive overview of leveraging WebAssembly to run Go code efficiently in web environments:

• WebAssembly provides a compact executable format for the web
• The Go compiler directly targets WebAssembly
• Compiled Go modules run in browsers and Node.js
• Shared memory and JSON encoding enable data passing
• Concurrency features like goroutines still work nicely
• Debugging requires custom tooling and source maps
• DOM APIs allow interacting with web content
• Performance may need tuning but can match Go standlone

The combination of WebAssembly and Go is opening up new possibilities like tiny footprints and fast binaries for web deployment. As browser support and tooling matures, WebAssembly will become an impactful compilation target for Go developers.

Frequently Asked Questions

Here are some common questions about Go and WebAssembly:

Q: Does WebAssembly replace JavaScript?

A: No, WebAssembly complements and integrates with JavaScript. They can work together in the same app.

Q: What are the benefits of running Go in WebAssembly?

A: Go WebAssembly provides great performance while compiling to small binaries that load fast. This expands use cases for Go.

Q: Does the full Go standard library work in WebAssembly?

A: Most standard packages work but some OS-specific ones like networking don’t apply to WebAssembly’s sandboxed environment.

Q: How do you debug Go WebAssembly modules?

A: Use print statements, source maps, browser DevTools, the Node.js debugger, GDB, and other specialized tooling.

Q: Can WebAssembly use multiple threads?

A: Not yet, but threads are on the roadmap. For now, you can spawn goroutines but execution is single-threaded.

Q: Is WebAssembly only for the browser?

A: No, runtimes like Wasmer also allow running WebAssembly outside the browser, like server-side.

Q: What are some examples of using Go and WebAssembly together?

A: Math/physics simulations, image processing, compression, running C bindings, adding backend to frontend, algorithms in browser, tiny microservices.