// Building a Golem application. Use when asked to build a Golem project, compile components to WASM, or troubleshoot build errors.
| name | golem-build |
| description | Building a Golem application. Use when asked to build a Golem project, compile components to WASM, or troubleshoot build errors. |
golem buildBoth golem and golem-cli can be used — all commands below work with either binary.
golem build --yes
Run this from the application root directory (where the root golem.yaml is located). It builds all components defined in the project. Always pass --yes to avoid interactive prompts.
golem build DoesThe build is a multi-step pipeline:
cargo for Rust, npm/node for TypeScript).golem.yaml for each component. These commands are language-specific:
cargo build --target wasm32-wasip2 (or with --release for the release preset).tsc for type checking, golem-typegen for metadata extraction, rollup for bundling, then injects the bundle into a prebuilt QuickJS WASM and optionally preinitializes it.golem build tracks file hashes of sources and targets. If nothing changed since the last build, steps are skipped automatically. Use --force-build to bypass this.
The final WASM artifact is placed in golem-temp/agents/ under the application root:
golem-temp/agents/<component_name_snake_case>_debug.wasmgolem-temp/agents/<component_name_snake_case>_release.wasmgolem-temp/agents/<component_name_snake_case>.wasmgolem-temp/agents/<component_name_snake_case>.wasmThe component name in snake_case is derived from the component name in golem.yaml. For example, a component named my-app:rust-main produces my_app_rust_main_debug.wasm.
| Option | Description |
|---|---|
[COMPONENT_NAME]... | Build only specific components (by default, all components are built) |
-s, --step <STEP> | Run specific build step(s): check, build, add-metadata, gen-bridge |
--skip-check | Skip build-time requirement checks |
--force-build | Skip up-to-date checks, rebuild everything |
-P, --preset <PRESET> | Select a component preset (e.g., release) |
-Y, --yes | Non-interactive mode — always use this flag |
golem.yamlBuild commands are defined per component template and preset in golem.yaml:
componentTemplates:
rust:
presets:
debug:
default: true
build:
- command: cargo build --target wasm32-wasip2
componentWasm: "target/wasm32-wasip2/debug/<name>.wasm"
outputWasm: "golem-temp/agents/<name>_debug.wasm"
The build section is a list of steps. Each step can be:
command: — a shell command to executeinjectToPrebuiltQuickjs: — injects a JS bundle into a QuickJS WASM (TypeScript/Scala only)preinitializeJs: — preinitializes the JS runtime in the WASM (TypeScript/Scala only)Each step can specify sources and targets for incremental builds, dir for the working directory, and env for environment variables.
golem clean
This removes golem-temp/ and any other directories listed in the clean section of each preset.
wasm32-wasip2 target (Rust): run rustup target add wasm32-wasip2golem build automatically runs npm install if package.json is present but node_modules is missing.ts source files; the tsc step runs with --noEmit false --emitDeclarationOnlyFor a deeper breakdown of build pipeline stages, dependency auto-fix behavior, and manifest tracing, load golem-troubleshoot-build.
golem-troubleshoot-build when a build fails or when diagnosing manifest/configuration issuesAdding a new component or agent templates to an existing Golem application. Use when adding a second component, adding agent templates like human-in-the-loop or snapshotting to an existing component, or converting a single-component app to multi-component.
Defining environment variables for Golem agents in `golem.yaml` (`env`, `envDefaults`, `secretDefaults`) or via CLI. Use when adding, setting, or overriding env vars on a component, agent, template, preset, or environment, or when wiring template substitution and merge modes.
Adding initial files to Golem agent filesystems via the `files:` section in `golem.yaml`. Use when provisioning local or remote files into an agent's virtual filesystem, setting read-only / read-write permissions, or configuring file mounts at the component, agent, template, or preset level.
Managing Golem plugins — listing available plugins, installing and configuring plugins via golem.yaml or CLI, and understanding built-in plugins like the OTLP exporter.
Understanding Golem CLI profiles, application environments, and component presets. Use when configuring deployment targets, switching between local and cloud servers, managing CLI profiles, defining environment-specific presets, or understanding how environments, presets, and profiles interact.
Rolling back a Golem deployment to a previous revision or version. Use when reverting a deployment, restoring a prior environment state, or recovering from a bad deploy.