Nuxt + WebSockets Starter

Nuxt + WebSockets Starter

Minimal realtime starter built with Nuxt (Nuxt 5 + Nitro v3), Nuxt UI, and the Vercel Functions WebSockets beta. Move your cursor and everyone in the room sees it live — presence, cursors, and emoji reactions over a single WebSocket connection. No auth, no client SDK.

Deploy

No environment variables and no external services — the realtime layer runs entirely on native WebSocket pub/sub (see How it works).

Run locally

1
npx giget@latest gh:vercel/examples/websockets/nuxt my-realtime-app
2
cd my-realtime-app
3
pnpm install
4
pnpm dev

Open http://localhost:3000 in two browser tabs (or share the URL) to see live cursors, presence, and reactions.

How it works

A Vercel Function can accept a WebSocket upgrade and keep a bidirectional connection open. Nitro v3 — which powers Nuxt's server — ships native WebSocket support through crossws, enabled with a single flag:

1
// nuxt.config.ts
2
export default defineNuxtConfig({
3
  nitro: {
4
    experimental: {
5
      websocket: true,
6
    },
7
  },
8
})

The headline: one transport, every environment. The same defineWebSocketHandler at /api/ws powers local dev and production — locally through Nitro's dev server, on Vercel through the preset's crossws/adapters/vercel bridge, which hands the handler the runtime's socket upgrade. There's no Vercel-specific code path and no experimental_upgradeWebSocket bridge to maintain.

All room logic lives in the handler server/api/ws.ts itself.

State and pub/sub

Each connection subscribes to a single room topic. Cursor moves, reactions, and join/leave events are broadcast with crossws's native peer.publish (server/api/ws.ts) — no external store and no client SDK. The connected roster is held in memory and replayed to each client in the welcome frame on connect, so a reconnect rebuilds it from scratch.

Architecture

1
app/
2
├── pages/index.vue            # page composition
3
├── composables/               # useRealtime (connection, reconnect, heartbeat)
4
└── components/                # LiveCanvas, Cursor, PresenceBar, HeroBackdrop
5

6
shared/
7
└── types/realtime.ts          # ClientMessage / ServerMessage / Peer — the wire protocol
8

9
server/
10
├── api/ws.ts                  # /api/ws — native WebSocket handler + room pub/sub
11
└── utils/
12
    └── identity.ts            # anonymous identity (name + color) per connection

Reconnects

WebSocket connections close when a Vercel Function reaches its maximum duration. The client reconnects with exponential backoff and reloads the roster from the welcome frame on each new connection — see useRealtime.ts (app/composables/useRealtime.ts).

A lightweight heartbeat (ping/pong) runs over the same socket so the client can detect a half-open connection (a missed pong) and force a reconnect. On disconnect, the server's close/error handlers publish a leave frame so the peer drops from everyone's roster.

Adapting this starter

• Identity — swap the anonymous name/color in server/utils/identity.ts (server/utils/identity.ts) for your authenticated user.
• New message types — add a variant to ClientMessage / ServerMessage in shared/types/realtime.ts (shared/types/realtime.ts), then handle it in the handler (server/api/ws.ts). The types are shared, so the client and server stay in sync.
• Rooms — key the topic by a room id to isolate multiple rooms. Nitro also derives a pub/sub namespace from the connection path, so per-room routes work out of the box.

Links

• Vercel WebSockets docs
• Nitro WebSocket docs
• Nuxt
• Nuxt UI

License

Published under the MIT license.