partysocket

PartySocket is a WebSocket client that implements the same interface as the browser’s native WebSocket API, but adds the resilience that real applications need: automatic reconnection with configurable backoff, buffering of outgoing messages while disconnected, connection-timeout handling, and the ability to change the server URL between reconnect attempts. It began as a fork of reconnecting-websocket, updated with pending fixes, then extended by the Cloudflare/PartyKit team with first-class helpers for connecting to PartyKit and PartyServer (Durable Object) rooms by host/room/party, plus React hooks for using it idiomatically inside components.

Because it has no dependency on window, the DOM, or a particular event-emitter library, it runs unmodified in browsers, Service Workers, Node.js, React Native, Cloudflare Workers, and Deno/Bun, making it a practical choice any time an app needs one reliable WebSocket client across multiple runtimes.

What You Get

• A WebSocket-API-compatible client class that’s a drop-in replacement for the native constructor
• Automatic reconnection with configurable min/max delay, backoff growth factor, and retry limits
• Outgoing message buffering while disconnected, flushed automatically once the connection reopens
• A PartySocket subclass with host/room/party/query URL construction for PartyKit and PartyServer rooms, plus a matching PartySocket.fetch helper
• React hooks (usePartySocket, useWebSocket) exposed via dedicated partysocket/react and partysocket/use-ws entry points
• An event-target-polyfill sub-export for environments missing a global EventTarget/Event

Common Use Cases

• Adding resilient, auto-reconnecting WebSocket connections to a web or React Native app without hand-rolling backoff logic
• Connecting a frontend to Cloudflare Durable Object-backed realtime backends built with PartyKit or PartyServer
• Sharing one WebSocket client implementation across browser, Node.js, and edge/Worker code paths

Under The Hood

Architecture - The package layers three pieces on top of a core reconnecting-WebSocket implementation. src/ws.ts (722 lines) implements ReconnectingWebSocket: it wraps a real WebSocket constructor, tracks retry/backoff state, re-emits browser-standard open/close/error/message events, and includes separate event-cloning paths for browser vs. Node/React Native runtimes (cloneEventBrowser vs cloneEventNode) because native Event construction differs across them. src/index.ts layers PartySocket on top, translating host/room/party/query options into a ws:///wss:// URL (and a matching PartySocket.fetch for one-off HTTP calls to the same room) before delegating to the base class. src/react.ts, use-socket.ts, use-handlers.ts, and use-ws.ts add a React hook layer (usePartySocket, useWebSocket) that manages the socket’s lifecycle against component mount/unmount and re-renders. Tech Stack - Written entirely in TypeScript, built with tsdown into dual ESM/CJS output with generated .d.ts/.d.cts declarations, then reformatted with oxfmt. Linting is via oxlint, tests run under vitest, and the package lives in an npm-workspaces monorepo (cloudflare/partykit) versioned with Changesets. Runtime dependencies are minimal: only its own tiny event-target-polyfill package, with react as an optional peer dependency gated by peerDependenciesMeta. Code Quality - The package ships 13 test files under src/tests/ covering reconnection behavior, error handling, React Native compatibility, module-scope isolation, React hooks, React SSR, integration flows, edge cases, performance, and the fetch helper — unusually thorough for a client library of this size. Typing is strict throughout, with any usage limited to a handful of documented event-cloning casts flagged by inline oxlint-disable comments rather than silently suppressed. API Design - The headline design decision is drop-in compatibility with the native WebSocket constructor, so existing code can adopt it with a single import swap. On top of that it exposes purpose-built subpath exports (partysocket/ws, partysocket/react, partysocket/use-ws, partysocket/event-target-polyfill) so consumers only pull in the pieces they use, plus a small, well-documented Options object (backoff timings, retry caps, buffering limits) with sensible defaults that require zero configuration to get a working reconnecting socket.