gojs

README

Overview

When GOOS=js and GOARCH=wasm, Go's compiler targets WebAssembly Binary format (%.wasm).

Wazero's "wa-lang.org/wazero/imports/go" package allows you to run a %.wasm file compiled by Go. This is similar to what is implemented in wasm_exec.js. See https://wazero.io/languages/go/ for more.

Example

wazero includes an example that makes HTTP client requests.

Experimental

Go defines js "EXPERIMENTAL... exempt from the Go compatibility promise." Accordingly, wazero cannot guarantee this will work from release to release, or that usage will be relatively free of bugs. Due to this and the relatively high implementation overhead, most will choose TinyGo instead.

Documentation

Overview

Package gojs allows you to run wasm binaries compiled by Go when `GOOS=js` and `GOARCH=wasm`. See https://wazero.io/languages/go/ for more.

Experimental

Go defines js "EXPERIMENTAL... exempt from the Go compatibility promise." Accordingly, wazero cannot guarantee this will work from release to release, or that usage will be relatively free of bugs. Due to this and the relatively high implementation overhead, most will choose TinyGo instead.

Index

• func Run(ctx context.Context, r wazero.Runtime, compiled wazero.CompiledModule, ...) error
• func WithRoundTripper(ctx context.Context, rt http.RoundTripper) context.Context

Functions

func Run

func Run(ctx context.Context, r wazero.Runtime, compiled wazero.CompiledModule, config wazero.ModuleConfig) error

Run instantiates a new module and calls "run" with the given config.

Parameters

• ctx: context to use when instantiating the module and calling "run".
• r: runtime to instantiate both the host and guest (compiled) module in.
• compiled: guest binary compiled with `GOARCH=wasm GOOS=js`
• config: the configuration such as args, env or filesystem to use.

Example

After compiling your Wasm binary with wazero.Runtime's `CompileModule`, run it like below:

// Use compilation cache to reduce performance penalty of multiple runs.
ctx = experimental.WithCompilationCacheDirName(ctx, ".build")
// Execute the "run" function, which corresponds to "main" in stars/main.go.
err = gojs.Run(ctx, r, compiled, config)
if exitErr, ok := err.(*sys.ExitError); ok && exitErr.ExitCode() != 0 {
	log.Panicln(err)
} else if !ok {
	log.Panicln(err)
}

Notes

• Use wazero.RuntimeConfig `WithWasmCore2` to avoid needing to pick >1.0 features set by `GOWASM` or used internally by Run.
• Wasm generated by `GOARCH=wasm GOOS=js` is very slow to compile. Use experimental.WithCompilationCacheDirName to improve performance.
• Both the host and guest module are closed after being run.

func WithRoundTripper

func WithRoundTripper(ctx context.Context, rt http.RoundTripper) context.Context

WithRoundTripper sets the http.RoundTripper used to Run Wasm.

For example, if the code compiled via `GOARCH=wasm GOOS=js` uses http.RoundTripper, you can avoid failures by assigning an implementation like so:

ctx = gojs.WithRoundTripper(ctx, http.DefaultTransport)
err = gojs.Run(ctx, r, compiled, config)