Topazdocs
Build & Delivery

WASM & Playground

Choose among the Playground, Raw Web, Worker, and managed Web Application paths.

Topaz uses WebAssembly in products with different ownership models and trust boundaries. Choose the product path before selecting a command.

1. Playground: first browser experiment

The web Playground is an interactive authoring workspace for editing, checking, and running Topaz source without installing the CLI. The browser loads the compiler and interpreter WebAssembly inside a Worker. Build deployed managed applications with topaz build --target web-app; their product profile declares browser capabilities.

Start with First Program when you need the same experiment from an installed CLI.

2. Raw Web: an existing host calls Topaz

Choose Raw Web when an existing JavaScript ES-module host owns the UI and calls selected exported Topaz functions.

BASH
topaz build --target web main.tpz --release --out-dir web-product

The product contains topaz-web.js, topaz-web.d.ts, topaz-web.wasm, and the common artifact files. Import instantiateTopaz from the generated module and serve the directory over HTTP. The host must follow the generated typed ABI.

3. Worker: keep the same ABI off the main thread

Choose Worker when the existing host also needs generated request/response transport around the Raw Web product.

BASH
topaz build main.tpz --target web-worker --release --out-dir worker-product

This product adds topaz-web-worker.js and topaz-web-worker-client.js. This does not create a UI or grant extra capabilities. The JavaScript host still owns both.

4. Managed Web Application: Topaz owns the UI

Choose web-app when Topaz owns the model, messages, update logic, view, and declared browser capabilities.

BASH
topaz init --target web-app --root hello-web
topaz lock --root hello-web
topaz check --root hello-web --locked
topaz test hello-web/tests/app.tpz --root hello-web --locked
topaz dev --root hello-web --port 8000
topaz build --root hello-web --locked --release --out-dir web-app-product

This package-only target creates a complete static product with index.html, the checked topaz-app.js host, Raw Web files, capability metadata, and declared styles or assets. topaz dev is loopback-only and is not a production server.

Requirements and recovery

Raw Web, Worker, and managed Web builds require Rust with wasm32-unknown-unknown. The finished browser product does not require the Topaz CLI or Rust. Serve it over HTTP. Loading ES modules and WASM directly through file:// is not a supported path.

If the browser reports a host/runtime identity mismatch, deploy the complete directory from a single build instead of mixing old JavaScript with new WASM. If a managed output directory has changed, preserve it and build into a new empty directory.