Skip to content

docs(guides): add Cloudflare and PartyKit migration guides - #4389

Draft
NathanFlurry wants to merge 1 commit into
mainfrom
cf-cookbook
Draft

NathanFlurry wants to merge 1 commit into
mainfrom
cf-cookbook

Conversation

@NathanFlurry

@NathanFlurry NathanFlurry commented Mar 9, 2026 •

Copy link
Copy Markdown
Member

Description

Adds migration guides for moving from Cloudflare and PartyKit to Rivet Actors. This replaces the original cookbook version of this PR, which targeted the old website/ and scripts/skill-evals/ layout that no longer exists on main.

New guides in docs/actors/content/guides/, listed under a new Migrations group in the Guides sidebar:

  • migrate-cloudflare-durable-objects
  • migrate-cloudflare-agents
  • migrate-cloudflare-d1
  • migrate-cloudflare-queues
  • migrate-partykit

Every Rivet code sample is a real file under examples/docs/<slug>/, embedded with <CodeSnippet> and type-checked with the rest of examples/docs. Only the Cloudflare/PartyKit "before" samples are inline @nocheck blocks. The docs sync workflow already copies examples/docs/**, so no workflow changes are needed.

Changes from the original PR

  • Rewritten for RivetKit 3.x. The guides use SQLite (db() + c.db.execute) and c.vars only. They do not use c.state, conn.state, queues (c.queue, queues, handle.send()), or c.kv, since those are deprecated or being deprecated. Cloudflare Queues maps to a SQLite jobs table drained by an actor.
    The guides also don't link to the /actors/docs/deprecated/* pages, which aren't on main yet for queues and KV.
  • Fixed wrong APIs from the original (c.db.exec(...).toArray(), c.db.prepare().bind().first(), c.kv.list()), which @nocheck had hidden.
  • Shorter, public-facing guides. Dropped the agent-oriented "Status Summary" legends and "Validation Checklist" sections.
  • Links use the current /actors/docs/* paths.
  • Dropped: the skill-eval harness changes and evals (scripts/skill-evals/ was removed on main), the hand-written skill files (skills are now generated from the docs in the website repo), the cookbook icon/component changes (the website moved to its own repo), the stray examples/skill-eval-cf-do-hello-* directory, and the internal research docs under docs-internal/.
  • Moved to their product repos: the Cloudflare Workflows guide (docs(guides): add Cloudflare Workflows migration guide workflows#22) and the Cloudflare Sandbox guide (docs(guides): add Cloudflare Sandbox migration guide agents#389).

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?

  • pnpm exec tsc --noEmit -p . in examples/docs: no errors in the new migrate-* directories. The only errors are ones already on main in React/blog examples.
  • biome check on the new example directories and docs/actors/sidebar.json: clean.
  • A script checked that every <CodeSnippet> file and region exists and every internal link resolves.
  • Each guide was reviewed against the RivetKit source, and the findings were fixed.
  • Not done: running the examples against a live engine, or rendering the pages on the website.

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

🤖 Generated with Claude Code

@railway-app

railway-app Bot commented Mar 9, 2026 •

Copy link
Copy Markdown

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

Service Status Web Updated
website ❌ Build Failed (View Logs) Web Nov 6, 2026 at 8:23 pm UTC
frontend-cloud 😴 Sleeping (View Logs) Web Jul 21, 2026 at 11:01 am UTC
frontend-inspector 😴 Sleeping (View Logs) Web Jul 21, 2026 at 10:59 am UTC
ladle ✅ Success (View Logs) Web Jul 21, 2026 at 10:58 am UTC
mcp-hub ✅ Success (View Logs) Web Jul 21, 2026 at 10:52 am UTC

@pkg-pr-new

pkg-pr-new Bot commented Mar 9, 2026

Copy link
Copy Markdown
More templates

@rivetkit/cloudflare-workers

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/sqlite-vfs

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

@rivetkit/traces

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

@rivetkit/workflow-engine

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

@rivetkit/virtual-websocket

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 0e58cd1

@claude

claude Bot commented Mar 9, 2026 •

Copy link
Copy Markdown
Contributor

Review

This PR is mostly additive docs (Cloudflare/PartyKit migration cookbook guides, research docs) plus a rework of the scripts/skill-evals harness. Focused the review on the non-generated code: scripts/skill-evals/src/index.ts, justfile, pnpm-workspace.yaml, and the website cookbook components.

Likely unintentional: generated eval scratch project committed to examples/

examples/skill-eval-cf-do-hello-1773079211449/ (about 14.7k of the 32.7k added lines in this PR) looks like a leftover artifact from running the eval harness rather than an intentional example:

  • Its name follows the harness naming pattern skill-eval-{eval}-{timestamp} (see EVAL_PROJECTS_DIR usage in scripts/skill-evals/src/index.ts), and package.json has "name": "skill-eval-cf-do-hello".
  • It contains a nested original-template/ directory with a full Cloudflare Workers starter (package-lock.json, wrangler.json, a 10,848-line generated worker-configuration.d.ts) - the pre-migration snapshot the eval agent worked from, not example content.
  • It has no README.md, which examples/CLAUDE.md requires for every example.
  • Because pnpm-workspace.yaml already globs examples/*, this directory is now a real member of the pnpm workspace.

Since pnpm-workspace.yaml also gains .context/skill-eval-projects/* in this PR (so generated eval projects can resolve workspace packages via pnpm), and that path is not added to any .gitignore, this is probably exactly how the stray directory got staged and committed. Recommend dropping examples/skill-eval-cf-do-hello-1773079211449/ from the PR and adding .context/ (or .context/skill-eval-projects/) to the root .gitignore so this cannot recur.

Dead code left behind in scripts/skill-evals/src/index.ts

startDevServer, waitForServer, killServer, and extractServerUrl (plus the spawn/ChildProcess imports they require) are no longer called anywhere - the harness now expects the judge agent to start the dev server itself per the updated judge-system.md. Worth deleting this block instead of leaving it stranded.

Potential unhandled rejection on the early-stop path

In main(), the agent turn is raced against waitForProjectReady/waitForProjectScaffold:

const winner = await Promise.race([
  promptPromise.then((value) => ({ kind: "prompt" as const, value })),
  readyPromise.then((ready) => ({ kind: "ready" as const, ready })),
  scaffoldPromise.then((hasScaffold) => ({ kind: "scaffold" as const, hasScaffold })),
]);

When winner.kind === "ready", the code destroys the agent session and moves on, but promptPromise (the in-flight collectTurnText(agentSession, ...) call) is never awaited or given a .catch(). If session.prompt() rejects after destroySessionBestEffort tears down the session, that becomes an unhandled promise rejection in the eval process, which can crash the run for reasons unrelated to the eval itself. Worth attaching a no-op .catch() to the losing races once a winner is picked.

Minor

  • The rewritten try/catch in main() (roughly lines 890-936) has inconsistent indentation (mixing 2/3/4 tabs), suggesting node scripts/format/agent-format.mjs was not run on this file per repo convention.
  • The new scripts/skill-evals/tsconfig.json enables strict: true, but scripts/skill-evals/package.json has no typescript dependency or type-check script, so nothing currently enforces it in CI. Combined with the PR description noting no tests were run, it would be good to at least manually type-check this file given how much of the session/event handling logic changed.
  • Cookbook icon additions (icons.ts, CookbookCard.tsx, content.config.ts) look correct and the frontmatter icon: values used in the new .mdx files all match the COOKBOOK_ICONS keys (cloudflare, balloon).

Overall the harness improvements (structured session events, early-exit on scaffold readiness, richer judge diagnostics) are a reasonable direction; the main things worth fixing before merge are the accidental examples/ commit and the missing .gitignore entry.

Add migration guides for Cloudflare Durable Objects, Agents, D1, Queues
and PartyKit under the actors bundle's guides, with a Migrations group in
the sidebar. Every Rivet sample is a type-checked file under
examples/docs/<slug>/ and uses SQLite and c.vars only, avoiding actor
state, queues and KV.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@NathanFlurry NathanFlurry changed the title Add Cloudflare migration cookbook and evals docs(guides): add Cloudflare and PartyKit migration guides Nov 6, 2026
@NathanFlurry
NathanFlurry marked this pull request as draft November 6, 2026 20:23
@RivetAgent

Copy link
Copy Markdown
Contributor

The migration guides and examples look good; no high-confidence issues found.

No Blocking, Should-fix, or Nit findings. Checked SDK API usage, snippet references, and CLAUDE.md compliance; no applicable CLAUDE.md files were present.

Review was limited to the local checkout; GitHub metadata checks were unavailable because gh was unauthenticated.

Copy prompt to fix all
Fix all actionable findings in the latest Ironworks code review on PR rivet-dev/rivet#4389. Inspect every referenced location, address each finding without changing unrelated behavior, run the relevant tests, and summarize what changed.

This branch had an error being deployed

1 failed deployment
rivet-frontend / rivet-pr-4389 — 22c8f918 Deployed Nov 6, 2026 by railway-app[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants