Skip to content
workers-go
Esc
↑↓navigate↵open⌘Jpreview
On this page

Build and deploy

How the Go-to-Wasm build pipeline works — workers-assets-gen, wasm_exec.js, and wrangler.

A workers-go project deploys a JavaScript entry point that loads a Go Wasm binary. The templates set this up for you; this page explains the pieces.

The build pipeline

The template package.json build script does two things:

"build": "go run github.com/syumai/workers-go/cmd/workers-assets-gen -mode=go && GOOS=js GOARCH=wasm go build -o ./build/app.wasm ."
  1. workers-assets-gen populates the build/ directory with the runtime assets:
    • wasm_exec.js — the Go (or TinyGo) Wasm support file (-mode=go or -mode=tinygo).
    • runtime.mjs — the workers-go runtime for the target platform (-runtime=cloudflare).
    • Common assets such as the worker.mjs entry point.
  2. go build compiles your code with GOOS=js GOARCH=wasm into build/app.wasm.

wrangler.toml points main at ./build/worker.mjs and runs the build automatically:

main = "./build/worker.mjs"

[build]
command = "npm run build"

workers-assets-gen flags

Flag Values Default
-mode go, tinygo tinygo
-runtime cloudflare cloudflare
-o output directory build
-durable-objects comma-separated Durable Object class names (e.g. Counter,Room) (none)
-workflows comma-separated Workflow class names (e.g. MyWorkflow,Other) (none)
-entrypoints semicolon-separated Name or Name:method1,method2 RPC entrypoint specs (e.g. MyService:add,greet;Other) (none)

Each of these flags appends one subclass definition to the generated worker.mjs per name/spec — see the linked page for the wiring details (matching wrangler.toml binding, and the Register call on the Go side).

Go vs TinyGo

The worker-go template uses the standard Go toolchain (Go 1.24+). The worker-tinygo template uses TinyGo 0.42.0 or later, which produces a much smaller Wasm binary — worth it for faster cold starts. TinyGo 0.41.x cannot build net/http for Wasm.

A durable-object-go template is also available, preconfigured with the -durable-objects flag and a wrangler.toml binding/migration:

npm create cloudflare@latest -- --template github.com/syumai/workers-go/_templates/cloudflare/durable-object-go

Deploy

npm run deploy   # wrangler deploy

Wrangler runs the build command, uploads the Wasm binary and the JS entry point, and publishes the worker.

Was this page helpful?