Nitro WebSockets Starter

nitro-websockets

Vercel's Nitro + WebSockets Starter — a Nitro v3 + React app where everyone in the room sees each other's cursors live, with presence and emoji reactions over one WebSocket — running as one Cloudflare Worker whose room is a Durable Object, built by Nitro's own cloudflare_durable preset (in place of the Vercel Functions WebSockets beta), and packaged as an Orun baseline: one command takes a new app from nothing to live on stage and prod, in its own repository, under its own name — in ONE landing.

The template's code is the code: the React page, the wire protocol, and the one defineWebSocketHandler at /api/ws. What the port adds is the preset in vite.config.ts, the Worker's config with the Durable Object, the monorepo wrapper, a test package, the deploy contract, an /api/health route the deploy smoke-tests, and one change the room needs to survive the Durable Object hibernating (below); what it swaps is the platform's name and links in the page. What the baseline adds is everything needed to make a copy of it somebody else's — built the way cirrus-baseline is. See specs/epics/nitro-websockets for the design, the milestones and the as-built status.

The example is MIT-licensed (vercel/examples); its licence ships with the app as apps/web/LICENSE.md.

Instantiating an app

git clone --depth 1 --branch <baseline-tag> https://github.com/sourceplane/nitro-websockets
cd nitro-websockets
orun new --blueprint repo-blueprint.yaml --out ~/apps/acme-room --run-hooks --resume \
  --set reponame=acme-room --set productname="Acme Room" \
  --set githuborg=acme-inc --set subdomain=<workers-dev-subdomain>

Or, once the platform's registry lists it, from the Orun console (Baselines → nitro-websockets → Build). Two phases — 01-product (the repository, its CI and the whole app in one pull request, deployed to stage and prod by one convergence, smoke-tested) and 02-docs (the live deployment recorded) — each landing one pull request in the new repository. BOOTSTRAP.md is the operator guide; docs/phases/ has a page per phase.

The new repository receives the app only — the Worker, its tests, its CI, its tooling, a README of its own and its operating contract — renamed throughout to the app's name, repository and Cloudflare Worker. None of this repository's machinery ships, and nothing that ships names it.

What is here (the app)

Getting started

pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build            # vite build → apps/web/.output (the Worker and the page's assets)

Run it with Vite's dev server (Node), or the built Worker under workerd with its Durable Object:

pnpm --filter @app/web dev            # vite dev, http://localhost:3000
pnpm --filter @app/web preview        # wrangler dev over the build, http://localhost:8787
curl http://localhost:8787/api/health # {"status":"ok","name":"Nitro WebSockets Starter","environment":"local"}

Open the page in two tabs and move the cursor in one.

How the room runs on Cloudflare

Every WebSocket upgrade to /api/ws goes to ONE Durable Object, the room (Nitro's cloudflare_durable preset names it $DurableObject, instance server). crossws, Nitro's WebSocket layer, accepts each connection there as a hibernatable WebSocket, so peer.publish reaches every socket in the room, and a quiet room costs nothing while its sockets stay open: the runtime evicts the object and wakes it for the next message.

A wake keeps the sockets and nothing else: module memory and each peer's context are gone. The template kept its roster in a module Map and each peer's identity in peer.context, so after a wake a cursor was dropped (if (!identity) return) and a leave was never announced — measured under wrangler dev, which hibernates an idle room after about a minute. The port keeps the handler and changes where the state lives: each identity is written into its socket's serialized attachment beside crossws's own (peer id, URL, topics), and the roster is read from the room's live sockets. tests/web drives the room through crossws's adapter across a simulated wake.

How it maps to Vercel

CI