DEV Community

Cover image for Writing components in Go with TinyGo compiler - WebAssembly Component Model
Tophe
Tophe

Posted on

Writing components in Go with TinyGo compiler - WebAssembly Component Model

#webassembly #wasi #go #tinygo

Setup

Required tools for TinyGo WebAssembly Component Model support:

  • TinyGo compiler v0.39.0+: Compiles Go code to WebAssembly components
  • wkg: Resolves and bundles WIT dependencies into a single package
  • wasm-tools: Converts WebAssembly modules to components

Build Process

Go plugins require a specific build process due to TinyGo's Component Model requirements:

1. Prepare WIT files for TinyGo

TinyGo has specific requirements that differ from other languages. The prepare-wit-files.sh script (a custom script for this project) copies WIT files from crates/pluginlab/wit to go_modules/wit and uncomments TinyGo-specific lines:

./scripts/prepare-wit-files.sh -i crates/pluginlab/wit -o go_modules/wit -s "SPECIFIC TinyGo"
Enter fullscreen mode Exit fullscreen mode

Why this workflow exists: The go_modules/wit directory is gitignored and contains modified versions of the WIT files specifically for TinyGo. This workflow maintains crates/pluginlab/wit as the single source of truth for all WIT definitions, while automatically generating TinyGo-compatible versions.

Why this is needed: The wasip2 target of TinyGo assumes that component is targeting wasi:cli/command@0.2.0 and requires explicit inclusion of WASI imports. The script searches for lines containing "SPECIFIC TinyGo" and uncomments them:

world plugin-api {  // The wasip2 target of TinyGo assumes that the component is targeting // wasi:cli/command@0.2.0 world (part of wasi:cli), so it needs to // include the imports from that world. // It's only included for the versions of the wit files destined for TinyGo. - // include wasi:cli/imports@0.2.0; // SPECIFIC TinyGo - DO NOT CHANGE THIS LINE + include wasi:cli/imports@0.2.0; // SPECIFIC TinyGo - DO NOT CHANGE THIS LINE  import http-client; import host-state-plugin; export plugin; }
Enter fullscreen mode Exit fullscreen mode

2. Bundle WIT dependencies with wkg

Why wkg is used: TinyGo cannot resolve WIT imports on its own - it needs all dependencies to be either bundled into a single WASM file or pre-resolved into a local directory. For example, when TinyGo sees include wasi:cli/imports@0.2.0;, it doesn't know where to find that external package or what's inside it. The wkg tool handles dependency resolution by fetching all imported WIT interfaces and creating a complete WIT package:

cd go_modules/ wkg wit build
Enter fullscreen mode Exit fullscreen mode

This creates repl:api.wasm containing all the WIT definitions needed by the plugin. The command also generates a wkg.lock file that locks the dependency versions for reproducible builds.

3. Generate Go bindings

Use wit-bindgen-go to generate Go code from the bundled WIT package:

cd go_modules/plugin-name/ go tool wit-bindgen-go generate --world plugin-api --out internal ../repl:api.wasm
Enter fullscreen mode Exit fullscreen mode

This creates the internal/ directory with all the generated Go bindings for the plugin interfaces.

4. Compile with TinyGo

TinyGo compiles the Go code directly to a WebAssembly component:

cd go_modules/plugin-name/ tinygo build -target=wasip2 --wit-package ../repl:api.wasm --wit-world plugin-api -o plugin-name-go.wasm main.go
Enter fullscreen mode Exit fullscreen mode

File Structure

Project organization: Go plugins follow this structure in the repo:

go_modules/ wit/ # Modified WIT files for TinyGo plugin-api.wit # Contains TinyGo-specific includes shared.wit # Shared types and interfaces host-api.wit # Host API definitions repl:api.wasm # Bundled WIT package (from wkg) wkg.lock # Lock file for WIT dependencies (from wkg) plugin-echo/ # Plugin directory go.mod # Go module with wit-bindgen-go tool main.go # Plugin implementation internal/ # Generated bindings (from wit-bindgen-go) repl/api/plugin/ # Plugin interface bindings repl/api/transport/ # Transport type bindings wasi/ # WASI interface bindings plugin-echo-go.wasm # Final WebAssembly component
Enter fullscreen mode Exit fullscreen mode

Plugin Implementation

Standard pattern: Go plugins use the init() function to register their exports, following the WebAssembly Component Model pattern:

package main import ( "webassembly-repl/plugin-echo/internal/repl/api/plugin" "webassembly-repl/plugin-echo/internal/repl/api/transport" "go.bytecodealliance.org/cm" ) func init() { plugin.Exports.Name = func() string { return "echogo" } plugin.Exports.Man = func() string { return `... some man text ...` } plugin.Exports.Run = func(payload string) cm.Result[plugin.PluginResponse, plugin.PluginResponse, struct{}] { response := plugin.PluginResponse{ Status: transport.ReplStatusSuccess, Stdout: cm.Some(payload), Stderr: cm.None[string](), } return cm.OK[cm.Result[plugin.PluginResponse, plugin.PluginResponse, struct{}]](response) } } // main is required for the wasip2 target func main() {}
Enter fullscreen mode Exit fullscreen mode

Go Module Configuration

Required setup: The go.mod file must include the wit-bindgen-go tool as a Go tool dependency:

module webassembly-repl/plugin-echo go 1.24 tool go.bytecodealliance.org/cmd/wit-bindgen-go // ... other dependencies
Enter fullscreen mode Exit fullscreen mode

This allows the project to use go tool wit-bindgen-go commands for generating bindings.

📎 Here are links to:

Top comments (0)