Quickstart
This page takes you from an empty project to an Express server running in your browser tab, shown in an <iframe>. It is the same sequence every wcvm app follows:
1. Install
npm install wcvmwcvm is an ES module for the browser and has no runtime dependencies. You need a bundler or dev server that can serve a page with custom headers; the examples use Vite.
2. Serve a page that can boot
The page that calls boot() must be cross-origin isolated: it needs SharedArrayBuffer, which browsers only give to pages that send these two headers.
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corpWith Vite:
// vite.config.ts
import { defineConfig } from "vite";
const isolation = {
"Cross-Origin-Opener-Policy": "same-origin",
"Cross-Origin-Embedder-Policy": "require-corp",
};
export default defineConfig({ server: { headers: isolation }, preview: { headers: isolation } });boot() throws ERR_NOT_ISOLATED if they are missing. Configuring headers covers other hosts, third-party content, HTTPS and Content-Security-Policy.
The repository's playground is a complete working setup, including the Service Worker header the preview needs.
3. Boot
import { boot } from "wcvm";
const wc = boot(); // synchronous: returns straight away
await wc.ready; // resolves once the kernel worker is upCall boot() once per page and keep the instance for as long as the page lives. It starts the kernel, the filesystem worker and a worker for downloads; processes are started later, one worker each. spawn and every wc.fs call wait for ready themselves, so awaiting it is optional, but doing so is how you show a "starting" state or catch a failed boot (ERR_BOOT_TIMEOUT, ERR_WORKER).
To see something run before going further, here is the smallest possible program, live on this page:
await wc.fs.writeFile("/hello.js", `console.log("hello from", process.version)`);
const proc = await wc.spawn("node", ["hello.js"], { cwd: "/" });
console.log(await new Response(proc.stdout).text()); // hello from v24.18.0
console.log((await proc.exit).exitCode); // 04. Mount your files
The filesystem is in memory and starts empty. mount seeds a whole tree in one call, which is much faster than writing files one at a time:
await wc.fs.mount({
"package.json": {
file: {
contents: JSON.stringify({
name: "app",
dependencies: { express: "^4" },
}),
},
},
"server.js": {
file: {
contents: `
const app = require("express")();
app.get("/", (req, res) => res.send("hello from the browser"));
app.listen(3000, () => console.log("listening on 3000"));
`,
},
},
}, "/app");The second argument is where the tree goes (created if missing). A node is a file, a directory or a symlink; see Working with the file system.
5. Install dependencies
const install = await wc.spawn("npm", ["install"], { cwd: "/app" });
const { exitCode } = await install.exit;
if (exitCode !== 0) throw new Error("npm install failed");This is a real install from registry.npmjs.org into /app/node_modules. Always check the exit code before starting the server: a failed install otherwise shows up later as "Cannot find module".
To show progress, read the output while it runs (install.stdout is a stream of bytes; Running processes has a helper for it).
Speed
A cold install of a larger project takes seconds to tens of seconds, because every package is fetched through the browser. Persist the filesystem (boot({ persist: true })) and skip node_modules on later visits: see Persistence.
6. Start the server and show it
wcvm has no server-ready event. Instead it tells you when any sandbox server starts or stops listening on a virtual port, and a Service Worker relays an <iframe> to it:
const iframe = document.querySelector("iframe")!;
await wc.preview.enable(); // registers the Service Worker
wc.preview.onListen(({ port, listening }) => {
if (listening) iframe.src = wc.preview.url(port); // "/__wcvm_preview__/3000/"
});
const server = await wc.spawn("node", ["server.js"], { cwd: "/app" });preview.url(port) is a same-origin path, so the iframe needs no CORS setup. The preview has its own requirements (a Service Worker header, a base path for client-side routers): see Preview a dev server.
Putting it together
<iframe style="width: 100%; height: 360px; border: 1px solid #ccc"></iframe>
<pre id="log"></pre>import { boot } from "wcvm";
const log = document.getElementById("log")!;
const pump = async (stream: ReadableStream<Uint8Array>) => {
const reader = stream.getReader();
const decoder = new TextDecoder();
for (;;) {
const { value, done } = await reader.read();
if (done) return;
log.textContent += decoder.decode(value, { stream: true });
}
};
const wc = boot();
await wc.ready;
await wc.fs.mount({
"package.json": { file: { contents: JSON.stringify({ dependencies: { express: "^4" } }) } },
"server.js": {
file: {
contents: `require("express")().get("/", (q, r) => r.send("hello from the browser")).listen(3000);`,
},
},
}, "/app");
const install = await wc.spawn("npm", ["install"], { cwd: "/app" });
void pump(install.stdout);
if ((await install.exit).exitCode !== 0) throw new Error("npm install failed");
await wc.preview.enable();
wc.preview.onListen(({ port, listening }) => {
if (listening) document.querySelector("iframe")!.src = wc.preview.url(port);
});
const server = await wc.spawn("node", ["server.js"], { cwd: "/app" });
void pump(server.stdout);
void pump(server.stderr);Stopping
There is no teardown call for the instance itself: leaving the page ends everything. To stop a running program, call proc.kill(); it also kills everything that process started, which frees its ports. Do this when your UI closes a project, otherwise a dev server you stopped looking at keeps running.
Common first-run problems
| Symptom | Cause |
|---|---|
ERR_NOT_ISOLATED | The page is missing the two headers. Headers. |
| The iframe shows your own app or "Not Found" | The Service Worker does not control the page yet. Troubleshooting. |
npm install fails with Failed to fetch | The registry is not reachable from the browser. |
Cannot find module after a "successful" install | A package needs a postinstall step; wcvm's npm does not run lifecycle scripts. npm. |
Where next
- Working with the file system: seed, read, write, persist.
- Running processes: streams, stdin, a terminal, the shell and npm.
- Preview a dev server: Vite end to end.
- Frameworks: what to set for Next.js, Angular, Ember and others.
- Want to see it first? Open Studio, an IDE built on wcvm.