Compiling with GOOS=wasip1 GOARCH=wasm

Go's WASI target turns ordinary packages into portable .wasm modules.

The compile command mirrors cross-compilation to Linux or Windows - set GOOS and GOARCH, then go build.

Understanding which flags matter, and which files (wasm_exec.js) belong to a different target, keeps your build scripts and CI matrices correct.

Summary

GOOS=wasip1 with GOARCH=wasm selects the WASI Preview 1 syscall surface.

The Go linker emits a module importing wasi_snapshot_preview1 functions instead of platform-specific syscalls.

You execute the artifact with an external WASM host (wasmtime, wazero, Spin) rather than the go command.

Release builds commonly pass -ldflags="-s -w" to strip debug metadata.

Browser-target notes about wasm_exec.js do not apply to wasip1 output.

Recipe

Quick-reference recipe card - copy-paste ready.

GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o app.wasm .
wasmtime run app.wasm

When to reach for this:

• Portable CLI tools distributed as a single .wasm artifact
• Sandboxed plugins executed inside a Go service via wazero
• Edge functions on Spin/Fermyon or compatible WASM hosts
• CI-verified builds that must not depend on native OS binaries
• Shared business logic compiled once and embedded in multiple host apps

Working Example

package main
 
import (
    "encoding/json"
    "fmt"
    "os"
)
 
type config struct {
    Name string `json:"name"`
}
 
func main() {
    raw := os.Getenv("CONFIG_JSON")
    if raw == "" {
        fmt.Fprintln(os.Stderr, "CONFIG_JSON required")
        os.Exit(1)
    }
    var cfg config
    if err := json.Unmarshal([]byte(raw), &cfg); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    fmt.Printf("hello, %s\n", cfg.Name)
}

go mod init example.com/wasigreet
# save main.go, then:
GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o greet.wasm .
wasmtime run --env CONFIG_JSON='{"name":"Ada"}' greet.wasm

What this demonstrates:

• Standard library packages (encoding/json, os) compile for WASI without tags.
• Environment variables are host-provided capabilities (--env in wasmtime).
• Exit codes propagate to the host process like a native CLI.
• Error output on os.Stderr maps to host stderr streams.

Deep Dive

How It Works

• The Go compiler lowers goroutines and GC to WASM instructions plus runtime imports.
• wasip1 maps os file operations to WASI fd APIs the host must implement.
• _start export is the entry the host calls after instantiating linear memory.
• go mod and vendoring work the same as native builds; cgo is not available on this target.

Build Environment Reference

wasm_exec.js vs WASI

Do not copy GOROOT/misc/wasm/wasm_exec.js into WASI deployment bundles.

Go Notes

// Separate browser entry files - never compile these into wasip1 builds.
//go:build js && wasm
 
package browseronly

# Makefile pattern
build-wasi:
	GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o bin/app.wasm ./cmd/app

Gotchas

• Assuming go run works - There is no WASI emulator inside go run; you must execute with a WASM host. Fix: wrap wasmtime run or wazero in go:generate/Makefile targets.

• Filesystem writes without pre-open - os.Create("/tmp/x") fails if the host did not map /tmp. Fix: pass wasmtime run --dir /host/tmp::/tmp or configure wazero FSConfig.

• Mixing js/wasm files into WASI packages - Accidental syscall/js imports break wasip1 compilation. Fix: isolate browser code behind js && wasm build tags.

• Expecting full networking - WASI preview 1 does not guarantee TCP APIs on every runtime. Fix: confirm socket support or use Spin HTTP triggers.

• Huge binaries by surprise - Full Go runtime adds megabytes even for fmt.Println. Fix: measure size early; consider TinyGo or split hot paths.

• Stale GOOS=wasi - Older docs reference wasi; modern toolchains use wasip1. Fix: update scripts to wasip1 for Go 1.21+.

Alternatives

FAQs

Related

• Go on WebAssembly: Browser, WASI, and Embedded Paths - three-path overview
• WASI Host Runtimes: wasmtime, wazero & Spin - run and embed modules
• syscall/js: Go in the Browser - when you need js/wasm instead
• WASM Size Optimization: TinyGo vs gc WASM - linker and import tactics
• Go 1.26 WASM Runtime & Memory Improvements - runtime changes affecting WASI

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