Connections

For documentation on connecting to actors from clients, see the Clients documentation. For worked presence and chat patterns, see the cookbook: Live Cursors and Presence and Chat Room.

Parameters

When clients connect to an actor, they can pass connection parameters that are handled during the connection process. Use params for static values, or getParams when you need fresh connection data each time a connection opens.

For example:

Connection State

There are two ways to define an actor's connection state:

	<CodeSnippet file="examples/docs/actors-connections/conn-state-const.ts" />

	This value will be cloned for every new connection using `structuredClone`.
</Tab>

<Tab title="createConnState">
	Create connection state dynamically with a function called for each connection:

	<CodeSnippet file="examples/docs/actors-connections/conn-state-dynamic.ts" />
</Tab>

Connection Lifecycle

Each client connection goes through a series of lifecycle hooks that allow you to validate, initialize, and clean up connection-specific resources.

On Connect (per client)

• onBeforeConnect
• createConnState
• onConnect

Pending connections are not visible in c.conns while onBeforeConnect or createConnState is running. RivetKit adds the connection to c.conns after those hooks succeed and before onConnect runs.

On Disconnect (per client)

• onDisconnect

createConnState and connState

API Reference

There are two ways to define the initial state for connections:

1. connState: Define a constant object that will be used as the initial state for all connections
2. createConnState: A function that dynamically creates initial connection state based on connection parameters. Can be async.

Connections are not visible in c.conns until createConnState completes successfully.

onBeforeConnect

API Reference

The onBeforeConnect hook is called whenever a new client connects to the actor. Can be async. Clients can pass parameters when connecting, accessible via params. This hook is used for connection validation and can throw errors to reject connections.

The onBeforeConnect hook does NOT return connection state - it's used solely for validation.

Connections are not visible in c.conns while onBeforeConnect is running.

Connections cannot interact with the actor until this method completes successfully. Throwing an error will abort the connection. This can be used for authentication, see Authentication for details.

onConnect

API Reference

Executed after the client has successfully connected. Can be async. Receives the connection object as a second parameter.

By the time onConnect runs, the connection is visible in c.conns.

Messages will not be processed for this actor until this hook succeeds. Errors thrown from this hook will cause the client to disconnect.

onDisconnect

API Reference

Called when a client disconnects from the actor. Can be async. Receives the connection object as a second parameter. Use this to clean up any connection-specific resources.

Connection List

All active connections can be accessed through the context object's conns property. This is a Map<string, Conn> of all current connections, keyed by connection ID.

This is frequently used with conn.send(name, event) to send messages directly to clients. To send an event to all connections at once, use c.broadcast() instead. See Events for more details on broadcasting.

For example:

Disconnecting clients

Connections can be disconnected from within an action:

If you need to wait for the disconnection to complete, you can use await:

This ensures the underlying network connections close cleanly before continuing.

API Reference

• Conn - Connection interface
• ConnInitContext - Connection initialization context
• CreateConnStateContext - Context for creating connection state
• OnBeforeConnectContext - Pre-connection lifecycle hook context
• OnConnectContext - Post-connection lifecycle hook context
• ActorConn - Typed connection from client side