Adding or modifying WIT (WebAssembly Interface Types) interfaces. Use when changing .wit files, updating WIT dependencies, or working with component interfaces.
Golem uses WIT (WebAssembly Interface Types) to define component interfaces. WIT files are centrally managed and synchronized across multiple sub-projects.
The root wit/ directory is the source of truth:
wit/
├── host.wit # Core Golem host interface
├── deps.toml # WIT dependency declarations
├── deps.lock # Locked dependency versions
└── deps/ # Fetched WIT dependencies
├── io/
├── clocks/
├── golem-1.x/
├── golem-core/
├── golem-agent/
└── logging/
WIT files are copied to these sub-projects by cargo make wit:
| Target | WIT deps copied |
|---|---|
golem-wasm/wit/deps/ | io, clocks, golem-1.x, golem-core |
golem-common/wit/deps/ |
| io, clocks, golem-1.x, golem-core, golem-agent |
cli/golem-cli/wit/deps/ | clocks, io, golem-1.x, golem-core, golem-agent, logging |
sdks/rust/golem-rust/wit/deps/ | All deps + golem-ai |
sdks/ts/wit/deps/ | All deps + golem-ai |
test-components/oplog-processor/wit/deps/ | All deps |
Never manually edit files in any wit/deps/ directory. They are overwritten by cargo make wit.
Edit the relevant .wit file in the root wit/ directory (e.g., wit/host.wit or a file under wit/deps/).
If editing a dependency managed by deps.toml, you may need to update the dependency version in wit/deps.toml first.
cargo make wit
This removes all wit/deps/ directories in sub-projects and re-copies the correct subset from the root.
cargo make check-wit
This runs cargo make wit and then checks git diff to ensure the committed WIT files match what the sync produces. If this fails in CI, you forgot to run cargo make wit.
cargo make build
WIT changes affect generated bindings in multiple crates. A full build ensures all bindings are regenerated correctly. If the change affects SDK-facing types, also run the relevant SDK test suites before considering the work complete.
Edit wit/deps.toml to add the new dependency.
cargo make wit
If the new dependency needs to be available in specific sub-projects, edit Makefile.toml to add the copy step in the appropriate wit-* task (e.g., wit-golem-wasm, wit-golem-common, wit-golem-cli, wit-sdks, wit-test-components).
WIT changes can have wide-reaching effects:
| What changed | What needs rebuilding |
|---|---|
Core interfaces (golem-1.x, golem-core) | Everything: services, SDKs, test components |
Agent interfaces (golem-agent) | golem-common, CLI, SDKs, agent test components |
SDK-only interfaces (golem-ai) | SDKs only |
Host interface (host.wit) | Worker executor, services |
If WIT changes affect SDK interfaces:
golem-rust (bindings are generated via wit_bindgen::generate!)npx pnpm run build in sdks/ts/), then rebuild agent template WASM (npx pnpm run build-agent-template)agent_guest.wasm, adjust Scala SDK types or codecs if the WIT shape changed, and run the relevant Scala test suitesAGENTS.md)wit/ directory (not in a wit/deps/ copy)cargo make wit run to synchronizecargo make check-wit passesMakefile.toml sync tasks updated if a new dependency was addedcargo make build succeedscargo make fix run before PR