PartyKit: Real-Time Collaboration English for Web Developers

PartyKit is a platform for building real-time collaborative applications using WebSockets. You write a server class that runs in the cloud and handles connections, messages, and state for each “room”, while the client connects using a simple WebSocket-based SDK. PartyKit is often used for collaborative editing, presence indicators, multiplayer games, and live dashboards. This post explains the vocabulary you will encounter when reading PartyKit documentation or working on a real-time feature.

Server-Side Vocabulary

PartyServer — the TypeScript class you author on the server side, which PartyKit instantiates once per room; it exposes lifecycle methods such as onConnect, onMessage, and onClose that you override to implement your logic.

“We wrote a PartyServer class for the collaborative whiteboard feature that stores the canvas state in the room’s storage and broadcasts updates to all connected clients.”

onConnect — the lifecycle method called each time a new client establishes a WebSocket connection to the room; you use it to send the new client the current room state so it can catch up immediately.

“In onConnect, we fetch the latest document state from room storage and send it directly to the newly connected client before it can receive any new broadcasts.”

onMessage — the lifecycle method called every time a client sends a message to the server; it receives the raw message string and the connection object of the sender.

“Our onMessage handler parses the incoming JSON operation, applies it to the shared state, and then broadcasts the change to all other connected clients.”

onClose — the lifecycle method called when a client’s WebSocket connection closes, either because the user navigated away or because of a network error; used to update presence information.

“The onClose method removes the disconnected user from the presence list and broadcasts the updated list to the remaining clients so the cursor count stays accurate.”

Rooms and Connections

room — a logical unit of isolation in PartyKit; each room has its own PartyServer instance, its own persistent storage, and its own set of connected clients, identified by a unique room name in the URL.

“We create a separate room for each document in the editor so users working on different documents never receive each other’s updates.”

party/client connection — the client-side PartySocket (or native WebSocket) instance that connects to a specific room URL; it emits standard WebSocket events like open, message, and close.

“We open a party/client connection when the user opens a document and close it when they navigate away, preventing open connections from accumulating.”

connection ID — the unique identifier PartyKit assigns to each individual WebSocket connection; you use it to send a message to a specific client rather than broadcasting to all clients in the room.

“We store each client’s connection ID alongside their username so the server can send direct private messages to a specific participant without alerting others.”

Messaging and Broadcasting

broadcast — the action of sending a message to all currently connected clients in a room; the PartyServer’s room.broadcast() method handles this in a single call.

“After applying an edit operation to the shared document state, we call room.broadcast() to push the operation to every other client in under 20 ms.”

send — the method used to deliver a message to a single specific connection rather than broadcasting to all clients; called as connection.send(message) inside the server.

“We call connection.send() in onConnect to deliver the initial state only to the newly joined client, avoiding an unnecessary broadcast to users who already have the state.”

Hibernation and Persistence

hibernation — a PartyKit feature that suspends a PartyServer instance when no clients are connected, preserving its storage but freeing compute resources; the instance wakes up automatically when a new client connects.

“Hibernation means our collaborative document server costs nothing when no one is actively editing, unlike a traditional WebSocket server that must run continuously.”

room storage — a persistent key-value store scoped to a single room that PartyKit provides to the PartyServer; data written to room storage survives hibernation and server restarts.

“We write the authoritative document state to room storage after every 50 operations so a restarting server can restore the latest version without replaying the entire event history.”

Practice

Create a minimal PartyKit server with onConnect, onMessage, and onClose methods. In onConnect, send the client the current value from room storage. In onMessage, update the storage and broadcast the change. In English, explain to a colleague why hibernation is important for cost management and what problem room storage solves for users who connect after the server has been asleep.