moxzi-web overviewalpha
What moxzi-web runs in a browser, how it compares with moxzid and the Internet Computer, and when to use page or worker mode.
moxzi-web is a JavaScript package that runs compiled Motoko actors inside a web page. It loads the same .wasm file you'd deploy to the Internet Computer and runs it with the same message rules: one message at a time per actor, rollback on trap, upgrades that keep state, timers, and calls between actors.
Use it for offline-capable apps, interactive tutorials and playgrounds, local-first prototypes, or to test an actor's logic in the browser before deploying it.
What runs where#
| Part | What it is |
|---|---|
| Your actor | Your .wasm, run by the browser's WebAssembly engine |
| The runtime | moxzi_web_bg.wasm, shipped in the package. It implements the IC's system API and message scheduling |
| The client library | Moxzi in moxzi.js. You call actors through it, with types from their Candid interface |
The runtime is the same code moxzid uses, compiled for the browser, so actors behave the same in both.
Page mode and worker mode#
| Page mode | Worker mode | |
|---|---|---|
| Start with | Moxzi.start({ glue }) | Moxzi.start({ worker: true }) |
| Where actors run | The page's main thread | A Web Worker |
| Stopping a runaway message | Only with meter: true | deadlineMs, or meter: true |
| HTTPS outcalls | No | Yes, with http: true and cross-origin isolation |
| Running the compiler in the page | Yes | No, a worker's stack is too small |
Everything else, including the method calls on actors, is the same in both modes.
Compared with moxzid and the IC#
moxzi-web | moxzid | Internet Computer | |
|---|---|---|---|
| Durable state | IndexedDB, or your own storage | Snapshot and log on disk | Replicated |
| Timers | When the page drives them (timerMs or tick()) | Yes | Yes |
| Instruction limits | Opt-in (meter: true) | Yes | Yes |
| Certified responses | No | No | Yes |
| Callable from outside | No, only from the page | Over HTTP | From anywhere |
An actor in a page can call canisters on the IC with ic-agent, in worker mode with http: true.
The compiler in the browser#
The Motoko compiler also runs in a page, and produces the same wasm as moxzi build. That's how the demos on this site compile code you type. It runs on the main thread.
Next steps#
- Getting started: add
moxzi-webto an app and run an actor. - API reference.
- Limits.