Run a dev server in the browser and preview it in an iframe

A web app is only half a demo until it is served. With NanoVM the server runs inside the visitor's tab: a plain Node.js http server listens on a virtual port, and a service worker turns iframe requests for /sw/<port>/… into connections to that port. Nothing is proxied to a backend and no tunnel is opened.

Serve something now

Each sample below is an ordinary Node program. Run starts it, waits until its port is listening, and loads the preview iframe; it keeps running until you press Stop. These samples run Node on the browser's own JavaScript engine (the fast host-engine tier), so they start in about a second.

const http = require("http");

http
  .createServer((req, res) => {
    res.setHeader("content-type", "text/html; charset=utf-8");
    res.end(`<h1>Served from your tab</h1>
<p>method: ${req.method} · path: ${req.url}</p>`);
  })
  .listen(8080, () => console.log("listening on :8080"));

Served from your tab

const http = require("http");
const fs = require("fs");
const path = require("path");

const root = "/work/public";
const types = { ".html": "text/html", ".css": "text/css", ".js": "text/javascript" };

http
  .createServer((req, res) => {
    const file = path.join(root, req.url === "/" ? "index.html" : req.url);
    fs.readFile(file, (err, body) => {
      if (err) return res.writeHead(404).end("not found");
      res.writeHead(200, { "content-type": types[path.extname(file)] || "application/octet-stream" });
      res.end(body);
    });
  })
  .listen(8080, () => console.log("serving", root));

Static site, zero servers

const http = require("http");

const todos = [
  { title: "write the server", done: true },
  { title: "preview it", done: true },
  { title: "deploy it", done: false },
];

http
  .createServer((req, res) => {
    const rows = todos.map((t) => `<li>${t.done ? "✓" : "·"} ${t.title}</li>`).join("");
    const left = todos.filter((t) => !t.done).length;
    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
    res.end(`<h2>Todo (${left} left)</h2><ul>${rows}</ul><small>port 3000 · node ${process.version}</small>`);
  })
  .listen(3000);

Todo (1 left)

How the preview works

Browsers can't open a listening socket, so the preview is built from three pieces that already exist in every modern browser:

• A virtual port table. When the guest program calls listen(8080), the kernel records the port. Nothing is bound on the real machine.
• A service worker. The SDK ships nano-sw.js. It intercepts requests under its scope's sw/<port>/ prefix and forwards each one, as raw HTTP bytes, to the page that hosts the VM.
• ServeBridge. On the page, the bridge receives the request, injects it as a new connection on that port (injectConnection), reads the HTTP response the server writes back, and hands it to the service worker, which answers the iframe.

iframe ── GET /sw/8080/style.css ──▶ service worker (nano-sw.js)
                                         │ postMessage(raw HTTP)
                                         ▼
                                   page: ServeBridge
                                         │ injectConnection(8080, bytes)
                                         ▼
                              server in the VM / host engine
                                         │ HTTP response bytes
iframe ◀──────── Response ───────── service worker ◀──┘

Because the iframe URL is same-origin, relative links, stylesheets, scripts and fetch() calls from the previewed app all route back to the in-tab server. The lower-level details of the in-VM socket injection are in virtual server.

The SDK calls

import { createNano, ServeBridge, startServer } from "@userland-run/nano-sdk";

const nano = await createNano({ image: { wasm: "/nano/nano.wasm" }, ramMB: 1800 });
await nano.installApp("node");
nano.fs.writeFile("/srv/server.js", serverSource);

const bridge = await ServeBridge.register({ injector: nano.virtualServer, swUrl: "/nano-sw.js" });
const { stop } = await startServer(nano, { node: ["/srv/server.js"] }, { readyPattern: /listening/i });

iframe.src = bridge.previewUrl(8080, "/"); // → "<scope>sw/8080/"
// … later
stop();
bridge.detach();

A server holds the VM

A NanoVM runs one thing at a time, and a listening server never "finishes". While a server launched with startServer runs on the VM, other VM calls on the same instance reject immediately with VM is busy serving instead of queueing forever. Call stop() first, or create a second Nano for concurrent work. This page applies the same rule: while one sample's server is running, other samples ask you to stop it first.

Current limitations

• BusyBox httpd inside the VM answers only one connection, so use a Node server for previews.
• A preview needs a service worker, which needs a secure context (HTTPS or localhost) and a same-origin nano-sw.js.
• Each request is injected as a fresh connection; long-lived streaming responses and WebSockets are not part of the bridge.
• Outbound network calls from the server go through the host's fetch and are subject to CORS — see networking.

FAQ