doc: default to serverless api

[NathanFlurry]

No description provided.

[railway-app]

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

Service	Status	Web	Updated (UTC)
frontend-inspector	❌ Build Failed (View Logs)	Web	Jan 12, 2026 at 9:51 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Jan 12, 2026 at 9:51 pm
website	🕒 Building (View Logs)	Web	Jan 12, 2026 at 9:49 pm

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore(rivetkit): update RIVETKIT_* env var names to RIVET_* #3839
• doc: default to serverless api #3833 👈 (View in Graphite)
• chore(rivetkit): preemptively start manager/engine before serverless/runner has started #3834
• chore(rivetkit): update cloudflare workers and nextjs to latest #3803
• feat(dashboard): provide ns when querying kv #3831 : 1 other dependent PR (#3561 )
• chore: update sdks #3830
• refactor: performance improvements for inspector #3452
• fix(dashboard): use proper timestamp for actor status #3809
• fix(engine): require namespace for actor id-specific routes #3828
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

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

[claude]

Pull Request Review: Default to Serverless API

Overview

This PR refactors the documentation to default to the serverless API pattern, which is a positive change for developer experience. The PR primarily updates documentation, examples, and adds new educational content about runtime modes and server setup.

✅ Strengths

1. Improved Developer Experience: Defaulting to serverless is the right choice for most users - it's simpler and more aligned with modern deployment patterns.

2. New Documentation Structure: The addition of runtime-modes.mdx and server-setup.mdx provides clear, comprehensive guidance on different deployment options.

3. Consistent API Endpoint Pattern: Standardizing on /api/rivet/* throughout the documentation improves consistency.

4. Better Component Reusability: The new React components (ConfigurationOptions, StepRunServer, StepSetupServer) promote DRY principles in documentation.

5. Cleaner Example Code: The Hono example now clearly shows the Rivet handler before custom endpoints, which is better for comprehension.

📋 Observations

Documentation Quality

• The new runtime modes documentation is well-structured with clear comparisons between serverless and runners
• Good use of diagrams to explain architecture
• Appropriate warnings about when to use runners vs serverless

Code Changes

• The example changes are minimal and focused
• No breaking changes to actual code, only documentation updates
• pnpm-lock.yaml changes appear to be routine dependency resolution

🔍 Potential Issues

1. Typo in llms-full.txt (Line ~3300)

In the backend quickstart section:

default app;

Should be:

export default app;

2. Missing export Statement

Location: website/public/llms-full.txt:3307

const client = createClient();

This appears in the quickstart but it's unclear if this is intentional or if export was accidentally removed.

3. Incomplete Code Snippet

In llms-full.txt around line 3310, there's a snippet that seems truncated:

serve();

This doesn't show what's being imported or the full context.

4. Inconsistent Endpoint Patterns

While most docs use /api/rivet/*, some historical references might still exist. Consider doing a full audit:

grep -r "/rivet" website/src/content/docs/

5. React Example Simplification

The React quickstart was significantly simplified (removed form input, connection status), which is good, but ensure that removed concepts are covered elsewhere in the docs.

🛡️ Security Considerations

• No security issues identified
• The examples don't introduce any OWASP vulnerabilities
• Proper use of typed clients throughout

🚀 Performance Considerations

• Documentation-only changes, no performance impact
• The serverless-first approach is generally better for auto-scaling

🧪 Test Coverage

• This PR is documentation-focused, so test coverage isn't directly applicable
• Consider adding tests for the new React components (ConfigurationOptions, StepRunServer, StepSetupServer) if your documentation tooling supports it

📝 Code Style & Best Practices

Follows Repository Conventions ✅

• Uses hard tabs (as per rustfmt.toml) where applicable
• Documentation follows existing patterns
• Component structure is consistent with the codebase

Areas for Improvement

1. llms-full.txt maintenance: This file appears to be generated. Consider documenting the generation process to avoid manual sync issues.

2. Component Documentation: The new React components could benefit from JSDoc comments explaining their purpose and props.

🎯 Recommendations

High Priority

1. Fix the typo: default app; → export default app; in llms-full.txt
2. Verify all code snippets in llms-full.txt are complete and valid

Medium Priority

1. Add JSDoc comments to the new React components
2. Consider adding a migration guide for users currently using the old runner-first pattern
3. Audit all docs for remaining /rivet references (without /api prefix)

Low Priority

1. Consider adding a visual diff showing before/after for the quickstart flow
2. Add troubleshooting section for common serverless deployment issues

✨ Summary

This is a well-executed documentation refactoring that improves the developer onboarding experience. The changes are focused, the new content is high quality, and the serverless-first approach is the right default.

The main issues are minor typos in the generated llms-full.txt file. Once those are addressed, this PR should be good to merge.

Recommendation: Approve with minor fixes required for the typos in llms-full.txt.

---

Review generated with attention to repository conventions per CLAUDE.md

[pkg-pr-new]

More templates

• actor-actions
• example-ai-agent
• example-ai-and-user-generated-actors-freestyle
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-cloudflare-workers-inline-client
• cross-actor-actions
• example-cursors
• example-cursors-raw-websocket
• custom-serverless
• example-sqlite
• example-elysia
• example-experimental-durable-streams-ai-agent
• hello-world
• example-hono
• hono-react
• example-kitchen-sink
• multi-region
• native-websockets
• next-js
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• scheduling
• state
• example-stream
• example-trpc

@rivetkit/cloudflare-workers

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/virtual-websocket

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: d14b367

[graphite-app]

Merge activity

• Jan 12, 10:01 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 12, 10:02 PM UTC: CI is running for this pull request on a draft pull request (#3842) due to your merge queue CI optimization settings.
• Jan 12, 10:03 PM UTC: Merged by the Graphite merge queue via draft PR: #3842.