A page creates one runtime. Programs borrow its filesystem, processes, pipes and network instead of each bringing their own. Bash Web and our browser build of Bun run on it.
import { createRuntime } from "waffle";
const runtime = createRuntime({ filesystem: { workerURL: "/fs-worker.js", mode: "memory" } });
try {
await runtime.filesystem.writeFile("/hello.txt", "hello from Waffle");
console.log(new TextDecoder().decode(await runtime.filesystem.readFile("/hello.txt")));
} finally {
await runtime.dispose();
}
hello from Waffle
That is the browser console of a cross-origin isolated page. Getting started builds and serves it step by step.
Why
- One tree for every program. WASI alone gives each program its own world. Waffle adds pids, jobs, signals, pipes between processes and one shared filesystem that the page and every guest see.
- Calls stay synchronous. A guest blocks in
Atomics.wait on shared memory while the page and other workers serve it, so Preview 1 semantics hold.
- Pay for what you use. The core bundle is 8,779 bytes gzipped. The process service loads on the first spawn.
bun run size enforces the core budget.
- Honest durability. A write returns when memory has it. Call
flush() to wait for IndexedDB. Storage says exactly what survives a closed tab.
The page owns every service. Guests only borrow them, and they never create a second runtime.
Quick start
Waffle is a library for a browser app, so there is no CLI. Install it with Bun, because Waffle's prepare step runs bun prepare.ts. Nothing is published to npm, so the command pins an exact commit and trusts Waffle's build step:
bun add github:ShaulLavo/waffle#4b9b6c668a59bd5aa52f0b87c3d76090b03706c3 --trust
Then:
- Add
fs-worker.ts (import "waffle/browser/fs-worker";) and the example above as app.ts.
- Bundle both entries with
bun build ./app.ts ./fs-worker.ts --outdir ./public --target browser --splitting.
- Serve
public/ with the Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers, then open the page and its console. The runtime needs SharedArrayBuffer, which browsers give only to cross-origin isolated pages.
Getting started has the HTML file, a short Bun server that sets the headers, and the failure you see without them. These steps were run with Bun 1.4.4, the version CI uses.
What you can do
How it works
The page calls createRuntime() once. The runtime starts a filesystem worker that owns the file tree in shared memory. Each process runs in its own worker and reads and writes that shared memory directly. The page-side supervisor tracks pids, jobs and signals, and loads on the first spawn. Pipes and TCP sockets are rings in shared buffers. Concepts walks through the ownership rules and the life of a spawn.
Docs
Getting started · Guides · Concepts · Reference · Status and limits · Troubleshooting · ADRs · Development · Landing site
Status
Pre-1.0 and experimental. package.json says 0.0.89 and private: true. There are no tags or releases and nothing on npm, so consumers pin a commit. Waffle promises no compatibility with older revisions.
- SAFE filesystem mode is reserved.
mode: "safe" throws UNSUPPORTED_VFS.
- Persistent storage has one writer at a time. A second tab waits or takes over.
- CI runs the browser suites in Chromium, Firefox and WebKit on Linux. Nothing is verified on iOS or Android.
Status and limits has the full list and the numbers.
License and contributing
MIT. Adapted upstream code is listed in docs/bun-patches.md and its licenses are in LICENSES/. To change the code, start with Development and AGENTS.md. Report security issues through SECURITY.md.
