WebAssembly & TinyGo Best Practices

Testing WASM builds in CI and avoiding syscall/js in server modules.

These rules keep WASM artifacts portable, sandbox-friendly, and sized appropriately from first spike through production hosts.

How to Use This List

• Apply during design review when a feature mentions WASM, TinyGo, wazero, or edge deploy.
• Add GOOS=wasip1 GOARCH=wasm compile and wasmtime run smoke steps to CI for guest packages.
• Pair with the Native Go vs TinyGo vs Rust WASM Decision Guide when toolchain choice is unsettled.
• Revisit after Go minor upgrades; WASM runtime behavior evolves (Go 1.26 heap chunking is a recent example).

A - Target and build hygiene

• Default server modules to wasip1/wasm. Reserve js/wasm for browser DOM requirements only.
• Never import syscall/js in WASI packages. Enforce with js && wasm build tags on browser files.
• Strip release WASM with -ldflags="-s -w". Keep unstripped artifacts in CI storage for crash triage.
• Pin toolchain versions in CI images. Record Go 1.26.x, TinyGo, wasmtime, and wazero together in the build log.
• Audit go list -deps for guest mains. Reject accidental net/http/pprof or test-only imports in plugin entrypoints.

B - CI and testing

• Compile WASM on every PR touching guest code. GOOS=wasip1 GOARCH=wasm go build ./... catches import regressions early.
• Smoke-run guests with wasmtime. Non-zero exit codes should fail the pipeline like native binaries.
• Mirror wazero embed tests if production hosts in Go. CLI success does not guarantee embed configuration is correct.
• Add TinyGo build jobs when TinyGo ships to prod. tinygo build -target=wasm may fail while gc builds pass.
• Log artifact sizes in CI. Track gc vs TinyGo bytes to detect dependency bloat over time.

C - Host runtime and sandboxing

• Pre-open directories with least privilege. Map only required host paths into guest namespaces (--dir / wazero FSConfig).
• Pass environment explicitly. Do not rely on implicit host env parity between dev laptops and production.
• Bound guest execution with context deadlines in wazero. Prevent runaway CPU in multi-tenant embedders.
• Cache compiled modules in long-running hosts. Re-instantiating cold compiles dominates latency.
• Choose wazero for pure-Go embedders; wasmtime for CLI/dev parity. Document why if you pick otherwise.

D - Size and toolchain selection

• Measure size before choosing gc vs TinyGo. Compare ls -lh on the same feature slice, not hello-world only.
• Re-evaluate gc WASM on Go 1.26+ when memory was the blocker. Smaller heap chunks help dense wazero pools.
• Use TinyGo for MCU and sub-megabyte edge caps. Verify stdlib and reflect limitations with a compile spike first.
• Avoid fat JSON/reflection frameworks in TinyGo guests. Prefer small structs and hand-tuned marshaling.
• Document per-plugin toolchain in plugin registry metadata. Operators should know which compiler built each .wasm.

E - Browser and syscall/js

• Version wasm_exec.js with your Go toolchain. Mismatch causes obscure import failures in browsers.
• Call js.Func.Release() when removing listeners. Prevent leaks on long-lived SPA pages.
• Block main with select {} in browser guests. Exiting main tears down the runtime before callbacks fire.
• Serve .wasm as application/wasm. Fix static server MIME maps for instantiateStreaming.
• Keep DOM surface area small. Prefer TS/React for layout; WASM for compute when possible.

F - Operations and security

• Treat WASM as immutable versioned artifacts. Publish hashes; roll forward by swapping module bytes deliberately.
• Do not mount host root into guests. One compromised plugin should not read the entire filesystem.
• Align WASI capability grants across dev and prod. Drift here is a common "works locally" failure mode.
• Upgrade Go for security fixes in crypto guests. Pin to 1.26.x and rebuild WASM on security releases.
• Run go fix modernizers on shared packages. Go 1.26 go fix keeps code idiomatic before cross-compiling to WASM.

FAQs

Related

• Compiling with GOOS=wasip1 GOARCH=wasm - build commands
• WASI Host Runtimes: wasmtime, wazero & Spin - host configuration
• syscall/js: Go in the Browser - browser-only interop
• Go 1.26 WASM Runtime & Memory Improvements - upgrade triggers
• WebAssembly & TinyGo Basics - hands-on starting points

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).