Configuration

Actor Configuration

This page documents the configuration options available when defining a RivetKit actor. The actor configuration is passed to the actor() function.

Basic Example

import { actor } from "rivetkit";

const myActor = actor({
  state: { count: 0 },

  actions: {
    increment: (c) => {
      c.state.count++;
      return c.state.count;
    },
  },
  options: {
	actionTimeout: 15_000,
  }
});

const registry = setup({
  use: { myActor },
});

TypeScript

Configuration Reference

state
nullable unknown
Initial state value for the actor. Cannot be used with createState.
createState
nullable unknown
Function to create initial state. Receives context and input. Cannot be used with state.
connState
nullable unknown
Initial connection state value. Cannot be used with createConnState.
createConnState
nullable unknown
Function to create connection state. Receives context and connection params. Cannot be used with connState.
vars
nullable unknown
Initial ephemeral variables value. Cannot be used with createVars.
createVars
nullable unknown
Function to create ephemeral variables. Receives context and driver context. Cannot be used with vars.
db
nullable unknown
Database provider instance for the actor.
onCreate
nullable unknown
Called when the actor is first initialized. Use to initialize state.
onDestroy
nullable unknown
Called when the actor is destroyed.
onWake
nullable unknown
Called when the actor wakes up and is ready to receive connections and actions.
onSleep
nullable unknown
Called when the actor is stopping or sleeping. Use to clean up resources.
onStateChange
nullable unknown
Called when the actor's state changes. State changes within this hook won't trigger recursion.
onBeforeConnect
nullable unknown
Called before a client connects. Throw an error to reject the connection.
onConnect
nullable unknown
Called when a client successfully connects.
onDisconnect
nullable unknown
Called when a client disconnects.
onBeforeActionResponse
nullable unknown
Called before sending an action response. Use to transform output.
onRequest
nullable unknown
Called for raw HTTP requests to /actors/{name}/http/* endpoints.
onWebSocket
nullable unknown
Called for raw WebSocket connections to /actors/{name}/websocket/* endpoints.
actions
nullable map
Map of action name to handler function.
options
nullable object
Actor options for timeouts and behavior configuration.
- options.createVarsTimeout
  nullable number
  Timeout in ms for createVars handler. Default: 5000
- options.createConnStateTimeout
  nullable number
  Timeout in ms for createConnState handler. Default: 5000
- options.onConnectTimeout
  nullable number
  Timeout in ms for onConnect handler. Default: 5000
- options.onSleepTimeout
  nullable number
  Timeout in ms for onSleep handler. Must be less than ACTOR_STOP_THRESHOLD_MS. Default: 5000
- options.onDestroyTimeout
  nullable number
  Timeout in ms for onDestroy handler. Default: 5000
- options.stateSaveInterval
  nullable number
  Interval in ms between automatic state saves. Default: 10000
- options.actionTimeout
  nullable number
  Timeout in ms for action handlers. Default: 60000
- options.waitUntilTimeout
  nullable number
  Max time in ms to wait for waitUntil background promises during shutdown. Default: 15000
- options.connectionLivenessTimeout
  nullable number
  Timeout in ms for connection liveness checks. Default: 2500
- options.connectionLivenessInterval
  nullable number
  Interval in ms between connection liveness checks. Default: 5000
- options.noSleep
  nullable boolean
  If true, the actor will never sleep. Default: false
- options.sleepTimeout
  nullable number
  Time in ms of inactivity before the actor sleeps. Default: 30000
- options.canHibernateWebSocket
  nullable boolean
  Whether WebSockets using onWebSocket can be hibernated. WebSockets using actions/events are hibernatable by default. Default: false

Registry Configuration: Configure the RivetKit registry
State: Managing actor state
Actions: Defining actor actions
Lifecycle: Actor lifecycle hooks

Actor Configuration

Basic Example

Configuration Reference

Related