Building WASM Components

Primatomic runs WebAssembly Components (Component Model), not plain WASM modules. Components let you define a stable interface in WIT (WebAssembly Interface Types) and generate bindings for multiple languages.

Determinism Required

Primatomic views need to be deterministic. Components cannot import WASI capabilities (filesystem, clocks, random, environment, stdio). Build with wasm32-unknown-unknown target to avoid WASI imports.

This guide covers:

1. Starting from a .wit interface (the contract)
2. Generating language bindings
3. Compiling your implementation into a component (.wasm)
4. Validating the output

Note

For the WIT interface that views must implement, see WASM Interface.

Tooling Overview

Tool	Purpose
cargo-component	Build Rust components (required for Rust)
wasm-tools	Inspect, validate, and convert components
wit-bindgen	Generate guest bindings (Rust)
wit-bindgen-go	Generate Go bindings
jco	Componentize JavaScript/TypeScript
componentize-py	Componentize Python

Common Workflow

1. Obtain the WIT Interface

Fetch the WIT interface using wkg:

wkg get --format wit primatomic:[email protected] --output ./wit

Registry Configuration

Before fetching, configure wkg to resolve the primatomic namespace. Run wkg config --edit and add:

[namespace_registries]
primatomic = "primatomic.com"

This only needs to be done once.

This downloads the interface files into your project’s wit/ directory:

your-project/
├── wit/
│   └── machine.wit
└── src/
    └── lib.rs

2. Generate Bindings

Most toolchains can generate bindings so your IDE and type checker understand what to implement. This step is optional but recommended.

3. Build a Reactor Component

Primatomic views are reactor components (library-like, called repeatedly), not command components (executable-like).

4. Validate the Artifact

A component prints as (component ...) while a core module prints as (module ...).

wasm-tools print path/to/component.wasm | head -1
wasm-tools component wit path/to/component.wasm

Install Shared Tools

wasm-tools

cargo install --locked wasm-tools

---

Rust

Rust builds components using cargo-component with the wasm32-unknown-unknown target.

Setup

# Install cargo-component
cargo install cargo-component

# Add the wasm32-unknown-unknown target
rustup target add wasm32-unknown-unknown

# Create a new project
cargo new --lib my-view
cd my-view

In Cargo.toml:

[lib]
crate-type = ["cdylib"]

[dependencies]
wit-bindgen = "0.41"

[profile.release]
opt-level = "s"
lto = true

Add WIT and Generate Bindings

Fetch the WIT interface, then generate bindings in src/lib.rs:

wkg get --format wit primatomic:[email protected] --output ./wit

wit_bindgen::generate!({
    path: "wit",
    world: "state-machine",
});

struct Component;

// Implement the generated Guest trait

Build

cargo component build --release --target wasm32-unknown-unknown

Output: target/wasm32-unknown-unknown/release/<crate-name>.wasm

Validate

# Verify it's a component (not a module)
wasm-tools print target/wasm32-unknown-unknown/release/<crate-name>.wasm | head -1

# Verify no WASI imports
wasm-tools print target/wasm32-unknown-unknown/release/<crate-name>.wasm | grep -i wasi
# (should produce no output)

# Inspect the WIT interface
wasm-tools component wit target/wasm32-unknown-unknown/release/<crate-name>.wasm

Tip

For a complete Rust example, see the counter implementation in WASM Interface.

---

Go (TinyGo)

TinyGo can build Preview 2 components using wit-bindgen-go for bindings.

WASI Imports

TinyGo’s wasip2 target includes WASI imports by default. You may need to use wasm-tools component strip to remove unused WASI imports, or verify your component doesn’t import WASI capabilities before deployment.

Setup

Fetch the WIT interface and resolve dependencies:

wkg get --format wit primatomic:[email protected] --output ./wit
wkg wit build

Generate Bindings

go tool wit-bindgen-go generate --world state-machine --out internal ./primatomic:[email protected]

Implement Exports

Set exported functions on the generated Exports struct (paths depend on your package structure).

Build

tinygo build -target=wasip2 \
  -o my-view.wasm \
  --wit-package primatomic:[email protected] \
  --wit-world state-machine \
  main.go

Validate

wasm-tools print my-view.wasm | head -1
wasm-tools component wit my-view.wasm

# Verify no WASI imports (should produce no output)
wasm-tools print my-view.wasm | grep -i wasi

---

JavaScript / TypeScript

Use jco to componentize an ES module.

Install

npm install -g @bytecodealliance/jco

Setup

Ensure your project uses ES modules ("type": "module" in package.json).

Componentize

jco componentize \
  --wit wit/machine.wit \
  --world-name state-machine \
  --out my-view.wasm \
  --disable=all \
  view.js

Caution

The --disable=all flag removes WASI capabilities for determinism. This means no console.log, real time, or random values. This is correct for Primatomic views.

Validate

wasm-tools print my-view.wasm | head -1
wasm-tools component wit my-view.wasm

---

Python

Install

pip install componentize-py

Generate Bindings (Optional)

componentize-py --wit-path wit --world state-machine bindings .

Implement

Implement the generated protocol class(es) from the bindings package.

Build

componentize-py \
  --wit-path wit/machine.wit \
  --world state-machine \
  componentize \
  my_view \
  -o my-view.wasm

Validate

wasm-tools print my-view.wasm | head -1
wasm-tools component wit my-view.wasm

# Verify no WASI imports (should produce no output)
wasm-tools print my-view.wasm | grep -i wasi

WASI Imports

componentize-py may include WASI imports. Verify your component doesn’t import WASI capabilities before deployment.

---

Troubleshooting

”Not a component”

You built a core module instead of a component. Verify:

wasm-tools print my-view.wasm | head -1

• (module = core wasm module (incorrect)
• (component = component (correct)

If using Rust, ensure you’re using cargo component build (not plain cargo build).

Component has WASI imports

If your component imports WASI capabilities, deployment will fail:

# Check for WASI imports
wasm-tools print my-view.wasm | grep -i wasi

Common causes:

• Rust: Built with wasm32-wasip1 or wasm32-wasip2 target instead of wasm32-unknown-unknown
• Go: Built with wasip2 target
• Dependencies: Some crates pull in WASI dependencies transitively

Fix by rebuilding with the correct target:

cargo component build --release --target wasm32-unknown-unknown

JS Logging/Time/Randomness Not Working

If you used --disable=all with jco componentize, WASI features are intentionally removed. This is expected for Primatomic views.

Deployment

Once validated, deploy your component:

curl -X POST https://api.primatomic.com/logs/$LOG_ID/views/my-view \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @my-view.wasm

See Quick Start for the complete deployment workflow.