Getting Started

Hotpipe documentation

Type-safe real-time events for React and Next.js. Define your events with Zod, subscribe with React hooks, publish from client or server. Clients connect directly to the Hotpipe API over WebSocket — your Next.js server is never in the hot path.

Quick start API reference

How it works

When a user loads your app, the PipeProvider calls your route handler to get an auth token. Your handler checks the session and signs a JWT with pipe permissions. The client then opens a WebSocket directly to the Hotpipe API — events flow between clients and server through the API, and your Next.js server stays completely out of the loop. No long-lived connections, no Vercel cost impact.

The Hotpipe API is stateless. It handles connection management and event fan-out. Your database is the source of truth — the API doesn't persist anything.

Environment variables

Hotpipe requires one environment variable on your server. Never expose this on the client.

HOTPIPE_SECRET — your secret for auth tokens and server-side publish

Concepts

Subscribing to events

Listen for real-time events with the usePipe hook.

Publishing events

Send events from the browser or server with full type safety.

Pipes & permissions

Control who can subscribe and publish on each pipe.

Connection & errors

Handle disconnections, reconnections, and buffering.

Build a Team Chat

Channel-based messaging with typing indicators and connection status.

Build a Real-Time Game

Player lobbies, action sync, and server-authoritative state.

Build a Live Auction

Server-only publishing, read-only viewers, and access revocation.

Client API

Hooks and providers for subscribing and publishing in the browser.

Server API

Auth handlers, event publishing, and access revocation from your server.