WebAssembly Overview (see WebAssembly & TinyGo section)

Go can target WebAssembly without cgo: the browser path uses GOOS=js GOARCH=wasm with syscall/js, and the server/edge path uses GOOS=wasip1 GOARCH=wasm for WASI hosts.

cgo is unavailable on wasm targets, so interop shifts to JavaScript bridges, WASI imports, or TinyGo for constrained builds.

Summary

WebAssembly is a portable alternative to native cgo when you deploy to browsers, edge runtimes, or sandboxed plugins.

Full build pipelines, size tuning, and host comparisons live in the WebAssembly & TinyGo section - this page orients cgo readers on when to pivot.

Recipe

Quick-reference recipe card - copy-paste ready.

# Browser wasm (syscall/js)
GOOS=js GOARCH=wasm go build -o app.wasm ./cmd/app
 
# WASI preview1 (servers, wazero, wasmtime)
GOOS=wasip1 GOARCH=wasm go build -o app.wasm ./cmd/app

When to reach for this:

• You need Go in the browser without native plugins.
• Edge platforms execute .wasm with WASI instead of libc.
• CGO_ENABLED=0 is mandatory and native syscalls are unavailable.
• Module size or embedded targets favor TinyGo over gc wasm.

Working Example

A minimal WASI program that writes to stdout (no cgo, no syscall/js).

// cmd/hello/main.go
package main
 
import "fmt"
 
func main() {
    fmt.Println("hello wasi")
}

GOOS=wasip1 GOARCH=wasm go build -o hello.wasm ./cmd/hello
wasmtime hello.wasm

What this demonstrates:

• Standard fmt works on wasip1 via WASI imports linked by the Go wasm runtime.
• Build tags can exclude cgo-only files with //go:build !wasm.
• Execution requires a wasm host (wasmtime, wazero, Spin, etc.), not ./hello.wasm directly.

Deep Dive

How It Works

• The gc toolchain compiles Go to WebAssembly with a target-specific syscall layer instead of libc cgo.
• syscall/js exposes JavaScript values and callbacks for GOOS=js; it is not used on wasip1.
• WASI maps files, clocks, and randomness to host imports - closer to server workloads than DOM APIs.
• TinyGo is a separate compiler producing smaller wasm at the cost of language/runtime subset.

cgo vs wasm Interop

Entry Points to Learn Next

Go Notes

//go:build !js && !wasm
 
package plugin
 
// cgo-only native implementation

//go:build js || wasm
 
package plugin
 
// wasm-safe stub or pure Go implementation

Split packages so interop code does not pull import "C" into wasm builds.

Gotchas

• Expecting cgo drivers on wasm - Build fails or tags exclude packages. Fix: Pure-Go drivers and wasm-specific build files.
• Running gc wasm in browser without wasm_exec.js - Loader errors. Fix: Follow Go wasm wiki wiring for your bundler.
• Assuming full net on js/wasm - Restricted by host sandboxes. Fix: Use fetch/WebSocket bridges documented for syscall/js.
• Huge wasm binaries from stdlib imports - Slow web loads. Fix: TinyGo or trim dependencies; see size guide in WebAssembly section.
• Mixing wasip1 and js tags - Different syscall sets. Fix: Separate main packages or explicit build tags per target.
• Ignoring host capability matrix - WASI previews differ across runtimes. Fix: Test on wazero/wasmtime versions you ship.

Alternatives

FAQs

Related

• Go on WebAssembly: Browser, WASI, and Embedded Paths - Section entry explainer
• WebAssembly & TinyGo Basics - Hands-on wasm tour
• syscall/js: Go in the Browser - DOM and JS interop
• syscall & Pure-Go Alternatives to CGO - Native non-cgo options
• Interop Decision Guide: CGO vs RPC vs Rewrite - Pick wasm vs native

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).