Using WebAssembly

You can call a JavaScript function from Go and call a Go function from WebAssembly:

  1. package main
  3. // This calls a JS function from Go.
  4. func main() {
  5.     println("adding two numbers:", add(2, 3)) // expecting 5
  6. }
  8. // This function is imported from JavaScript, as it doesn't define a body.
  9. // You should define a function named 'main.add' in the WebAssembly 'env'
  10. // module from JavaScript.
  11. func add(x, y int) int
  13. // This function is exported to JavaScript, so can be called using
  14. // exports.multiply() in JavaScript.
  15. //go:export multiply
  16. func multiply(x, y int) int {
  17.     return x * y;
  18. }

Related JavaScript would look something like this:

  1. // Providing the environment object, used in WebAssembly.instantiateStreaming.
  2. env: {
  3.     'main.add': function(x, y) {
  4.         return x + y
  5.     }
  6.     // ... other functions
  7. }
  9. // Calling the multiply function:
  10. console.log('multiplied two numbers:', wasm.exports.multiply(5, 3));

You can also simply execute code in func main(), like in the standard libraryimplementation of WebAssembly.

Building

If you have tinygo installed, it’s as simple as providing the correct target:

  1. tinygo build -o wasm.wasm -target wasm ./main.go

If you’re using the docker image, you need to mount your workspace into the image.Note the —no-debug flag, which reduces the size of the final binary by removingdebug symbols from the output. Also note that you must change the path to your Wasm file from /go/src/github.com/myuser/myrepo/wasm-main.go to whatever the actual path to your file is:

  1. docker run -v $GOPATH:/go -e "GOPATH=/go" tinygo/tinygo:0.8.0 tinygo build -o /go/src/github.com/myuser/myrepo/wasm.wasm -target wasm --no-debug /go/src/github.com/myuser/myrepo/wasm-main.go

Make sure you copy wasm_exec.js to your runtime environment:

  1. docker run -v $GOPATH:/go -e "GOPATH=/go" tinygo/tinygo:0.8.0 /bin/bash -c "cp /usr/local/tinygo/targets/wasm_exec.js /go/src/github.com/myuser/myrepo/

More complete examples are provided in the wasm examples.

How it works

Execution of the contents require a few JS helper functions which are calledfrom WebAssembly. We have defined these in tinygo/targets/wasm_exec.js. It isbased on $GOROOT/misc/wasm/wasm_exec.js from the standard library, but isslightly different. Ensure you are using the same version of wasm_exec.js asthe version of tinygo you are using to compile.

The general steps required to run the WebAssembly file in the browser includesloading it into JavaScript with WebAssembly.instantiateStreaming, orWebAssembly.instantiate in some browsers:

  1. const go = new Go(); // Defined in wasm_exec.js
  2. const WASM_URL = 'wasm.wasm';
  4. var wasm;
  6. if ('instantiateStreaming' in WebAssembly) {
  7.     WebAssembly.instantiateStreaming(fetch(WASM_URL), go.importObject).then(function (obj) {
  8.         wasm = obj.instance;
  9.         go.run(wasm);
  10.     })
  11. } else {
  12.     fetch(WASM_URL).then(resp =>
  13.         resp.arrayBuffer()
  14.     ).then(bytes =>
  15.         WebAssembly.instantiate(bytes, go.importObject).then(function (obj) {
  16.             wasm = obj.instance;
  17.             go.run(wasm);
  18.         })
  19.     )
  20. }

If you have used explicit exports, you can call them by invoking them under thewasm.exports namespace. See the export directory in the examples for anexample of this.

In addition to the JavaScript, it is important the wasm file is served with theContent-Typeheader set to application/wasm. Without it, most browsers won’t run it.

  1. package main
  3. import (
  4.     "log"
  5.     "net/http"
  6.     "strings"
  7. )
  9. const dir = "./html"
  11. func main() {
  12.     fs := http.FileServer(http.Dir(dir))
  13.     log.Print("Serving " + dir + " on http://localhost:8080")
  14.     http.ListenAndServe(":8080", http.HandlerFunc(func(resp http.ResponseWriter, req *http.Request) {
  15.         resp.Header().Add("Cache-Control", "no-cache")
  16.         if strings.HasSuffix(req.URL.Path, ".wasm") {
  17.             resp.Header().Set("content-type", "application/wasm")
  18.         }
  19.         fs.ServeHTTP(resp, req)
  20.     }))}

This simple server serves anything inside the ./html directory on port8080, setting any *.wasm files Content-Type header appropriately.

For development purposes (only!), it also sets the Cache-Control headerso your browser doesn’t cache the files. This is useful while developing, toensure your browser displays the newest wasm when you recompile.

In a production environment you probably wouldn’t want to set theCache-Control header like this. Caching is generally beneficial for endusers.

Further information on the Cache-Control header can be found here: