docs(actors): clarify saveState immediate vs throttled flush behavior

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[railway-app]

🚅 Deployed to the rivet-pr-4510 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
kitchen-sink	🕒 Building (View Logs)	Web	Mar 25, 2026 at 8:09 pm
mcp-hub	✅ Success (View Logs)	Web	Mar 25, 2026 at 8:08 pm
website	🕒 Building (View Logs)	Web	Mar 25, 2026 at 8:07 pm
frontend-inspector	😴 Sleeping (View Logs)	Web	Mar 25, 2026 at 5:57 pm
frontend-cloud	😴 Sleeping (View Logs)	Web	Mar 25, 2026 at 5:57 pm
ladle	❌ Build Failed (View Logs)	Web	Mar 25, 2026 at 5:44 pm

[NathanFlurry]

• docs(actors): clarify saveState immediate vs throttled flush behavior #4510 👈 (View in Graphite)
• fix(rivetkit): copy Buffer to Uint8Array in ensureUint8Array to fix .slice() semantics #4506 : 1 other dependent PR (#4502 )
• fix(rivetkit): setup database before lifecycle hooks for c.db availability #4494
• fix(rivetkit): remove drizzle-orm peer dep and add runtime version check #4492
• chore(skill): add version check to rivetkit skill #4491
• fix(rivetkit): prevent Turbopack from tracing sqlite-vfs dynamic import #4490
• fix(rivetkit): warn when manager port falls back to a different port #4489
• fix(rivetkit): clear connectableTs on actor sleep #4488
• fix(rivetkit): gate node:sqlite behind RIVETKIT_NODE_SQLITE env var #4487
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• example-elysia
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• example-multiplayer-game-patterns
• example-multiplayer-game-patterns-vercel
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4510

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@4510

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@4510

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@4510

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@4510

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@4510

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@4510

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4510

@rivetkit/traces

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/traces@4510

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4510

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@4510

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@4510

commit: 9165d2c

[claude]

PR Review: docs(actors): clarify saveState immediate vs throttled flush behavior

This is a small, focused documentation addition to website/src/content/docs/actors/state.mdx that explains the two modes of c.saveState(). I verified the content against the implementation in rivetkit-typescript/packages/rivetkit/src/actor/instance/state-manager.ts.

Accuracy Check

• Immediate mode ({ immediate: true }): Calls savePersistInner() directly - accurate
• Throttled mode (default): Schedules via savePersistThrottled(), awaits next flush cycle - accurate
• Default interval of 10 seconds: Matches stateSaveInterval: default(10_000) in actor/config.ts - accurate

Suggestions

Minor: maxWait option is undocumented

SaveStateOptions also exposes a maxWait field (maximum milliseconds before forcing a flush). It is a useful middle ground between full-immediate and fully-throttled saves that is worth a brief mention, e.g. c.saveState({ maxWait: 1000 }).

Minor: throttled behavior description is slightly imprecise

The doc says 'await will not resolve until the next flush cycle, which can take up to stateSaveInterval'. In practice the throttled path resolves sooner when a save was recently completed; it only approaches the full interval when no prior save has occurred recently. A small clarification like 'up to stateSaveInterval if no recent save has occurred' would be more accurate and avoid surprising callers.

Overall

Good addition. The distinction between immediate and throttled saves is non-obvious and worth documenting. The WebSocket handler callout at the end is helpful context. Both suggestions above are optional; the PR is mergeable as-is.

[graphite-app]

Merge activity

• Mar 25, 8:07 PM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.
• Mar 25, 8:09 PM UTC: Graphite rebased this pull request as part of a merge.
• Mar 25, 8:10 PM UTC: @NathanFlurry merged this pull request with Graphite.