Skip to main content

Multi-Client

Multiple clients can connect to the same Idyllic system instance simultaneously. When one client modifies state through an action, the change broadcasts to all connected clients automatically. This enables collaborative features—shared documents, multiplayer experiences, live dashboards—without additional pub/sub infrastructure.

Default Behavior

The instance ID determines which Durable Object clients connect to. Same ID = same state:
State changes broadcast to every connected client without configuration. When an action modifies a field, all clients see the update. When a stream produces content, all clients receive chunks.

Connection Tracking

Track connected clients with lifecycle methods:
Changes in lifecycle methods broadcast like any state modification:

Conflict Handling

Multiple clients calling actions that modify the same state get processed serially. The Durable Object executes one action at a time—last-write-wins:
For most applications this works well. For sophisticated needs like collaborative text editing, implement operational transforms or CRDTs within your actions.

Collaborative Patterns

Shared Cursors

Track cursor positions in shared state:

Turn-Based Interactions

Validate actions come from the correct user:

FAQ

Do all clients see the same state?

Yes. State lives on the server. All connected clients receive the same updates via WebSocket.

What happens with simultaneous actions?

The Durable Object processes actions serially. Both complete, but one finishes before the other starts. No race conditions.

How many clients can connect?

Hundreds work fine. For thousands, reduce update frequency and consider sharding.

What happens when a new client connects?

They immediately receive a full state snapshot, then incremental updates from there.

Can I have per-connection private state?

The state object is shared. For per-connection data, use connection metadata (doesn’t persist) or a map keyed by user ID in state (persists but visible to other clients).