WASM & TinyGo Build Review Skill

Target triple, binary size, and syscall/js misuse checks for agents - a cookbook-style Agent Skill for Go 1.26 and TinyGo WASM builds.

What This Skill Does

Produces a WASM build review checklist: correct GOOS/GOARCH, syscall/js vs syscall/wasmimport, TinyGo target tags, size budgets, host runtime compatibility (wazero, wasmtime), and forbidden imports - before merge.

When to Invoke

• PR adds GOOS=wasip1 GOARCH=wasm build targets
• TinyGo firmware or constrained WASM module changes
• Agent scaffolds browser WASM with syscall/js
• Binary size regression on edge deployment
• Host integration with wazero runtime

Inputs

Outputs

• Target triple validation table
• Import/syscall misuse findings
• Size report commands (wasm-objdump, twiggy, tinygo size)
• Host smoke test snippet for wazero
• Verification build commands

Guardrails

1. No syscall/js in WASI modules - browser-only API.
2. No cgo in standard WASM cross-compile unless documented exception.
3. TinyGo - verify board tag and scheduler; full Go stdlib may not apply.
4. Size budget - block new heavy deps without justification.
5. Do not use os/exec or raw sockets in WASM without host capability doc.
6. wazero API - verify at build; pin in skill header.

Recipe

Quick-reference recipe card - copy-paste ready.

# WASI module (Go 1.26)
GOOS=wasip1 GOARCH=wasm go build -o app.wasm ./cmd/wasi/
 
# Inspect exports and size
wasm-objdump -x app.wasm | head -40
ls -la app.wasm
 
# TinyGo constrained build (example - verify board)
tinygo build -target=wasi -o tiny.wasm ./cmd/edge/
 
# wazero smoke (host)
go test ./internal/wasmhost/... -run TestLoadModule -count=1

When to reach for this skill:

• Edge team ships KB-sized WASM artifacts
• Agent used fmt.Println and net/http in browser WASM draft
• CI added WASM target without size gate

Working Example

Step 0 - Classify target

See Go on WebAssembly: Browser, WASI, and Embedded Paths

Step 1 - Import audit

# Forbidden patterns in WASI
grep -rn 'syscall/js\|js\.Value' --include='*.go' ./cmd/wasi/
grep -rn 'cgo\|os/exec\|"net/http"' --include='*.go' ./cmd/wasi/

Step 2 - Size budget

ls -la app.wasm
# Optional: twiggy top for Rust-linked hosts; wasm-objdump for Go wasm

• Compare to budget in ticket (e.g. 500 KB gzip)
• See WASM Size Optimization: TinyGo vs GC WASM

Step 3 - Host smoke (wazero)

func TestLoadWASIModule(t *testing.T) {
    ctx := context.Background()
    r := wazero.NewRuntime(ctx)
    defer r.Close(ctx)
    mod, err := r.InstantiateWithConfig(ctx, wasmBytes,
        wazero.NewModuleConfig().WithStartFunctions("_initialize"))
    if err != nil {
        t.Fatal(err)
    }
    defer mod.Close(ctx)
}

• Verify instantiate, _initialize, and exported run/main per module contract
• See WASI Host Runtimes: Wasmtime, wazero, and Spin

Step 4 - TinyGo-specific

tinygo flash -target=pico -size=short ./cmd/firmware/   # example - verify board

• Scheduler: avoid blocking forever without host yield
• Check //go:build tinygo tags for divergent code paths

Deep Dive

Go 1.26 WASM runtime improvements may change alloc behavior - re-benchmark size after toolchain bump.

See Go 1.26 WASM Runtime and Memory Improvements

syscall/js requires DOM callbacks and js.FuncOf cleanup - leak review in browser targets.

WASI preview vs wasip1: build tags and host capability matrix must match deployment environment.

Gotchas

• Single main for both linux and wasm without build tags pulls wrong imports.
• Global variables bloat WASM init sections - prefer const and lazy init.
• Reflection and fmt cost size in TinyGo - audit format strings.
• Testing WASM on macOS host - ensure CI builds same triple as production.

Alternatives

FAQs

Related

• Agent Skills Basics - SKILL.md structure
• WebAssembly and TinyGo Basics - WASM intro
• Compiling with GOOS=wasip1 GOARCH=wasm - WASI build
• syscall/js: Go in the Browser - browser API
• TinyGo for Microcontrollers and Constrained WASM - TinyGo
• WASI Host Runtimes: Wasmtime, wazero, and Spin - hosts

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