World / Cloudflare
DocumentationArchitectureVercel comparison
GitHub

Run it

Build, deploy and operate

The repository root is an example application. The reusable World lives in packages/world-cloudflare. Deploy the minimal mode first, then add retained executors if you need them.

Start with the example

From the repository root
pnpm install
pnpm run build:workflow
pnpm exec wrangler dev

Building first generates the SDK workflow bundle and the package’s compiled output. Local execution can run flows in the main Worker without a dispatch namespace. The root README documents bindings, resource creation and the example HTTP routes.

The package remains private and unpublished. An npm name and licensing/release decisions are still open. Do not treat the docs as an announcement of a published package.

Know which config changes affect old runs

SettingWhat it controlsOperational rule
DEPLOYMENT_IDThe build identity stamped on new runs.Match the actual retained route when using WFP.
EXECUTOR_ROUTESRecorded deployment ID to executor script.Keep old routes and scripts while runs still use them.
SHARD_EPOCHSTime-based store, queue and index routing.Append only. Coordinate activation across deployments.
LOCATION_HINTRequested placement for new objects.Not residency; does not relocate existing objects.
WORKFLOW_VMEngine policy for new runs.QuickJS is the default here; run context retains the choice.
WORKFLOW_ENCRYPTION_SECRETPer-run payload key derivation.Keep the secret for old runs; rotation is not supported.
WORLD_RPC_TOKENOptional remote World HTTP endpoint.Endpoint is disabled without it. Keep it secret.

Deploy state first, then the retained executor

Use the repository’s explicit configs. The main deployment supplies the Durable Object classes and namespaces. The executor config references those resources and contains the workflow bundle. Create the dispatch namespace and populate the release map before admitting runs that depend on it.

Command shape; substitute your own config and namespace
pnpm run build:workflow
pnpm exec wrangler deploy --config wrangler.jsonc
pnpm exec wrangler deploy --config wrangler.executor.jsonc \
  --dispatch-namespace YOUR_NAMESPACE

Keep history in shard epochs unchanged. Preserve retained RPC names. Never delete an old executor simply because a newer deployment is live; check whether any runs still require it.

Test the adapter, the SDK and the deployment

Repository checks
pnpm run typecheck
pnpm exec tsc --noEmit --noUnusedLocals --noUnusedParameters -p tsconfig.json
pnpm test
pnpm run test:e2e

# Documentation application
pnpm --filter world-cloudflare-docs typecheck
pnpm --filter world-cloudflare-docs build
pnpm --filter world-cloudflare-docs test

Unit tests exercise state transitions and recovery. SDK contract/conformance coverage checks the adapter boundary. End-to-end lanes cover default, native, encrypted and spec-9 execution. Remote probes then test real Workers behavior that local workerd cannot establish.

Operational work still left

  • Decide retention and cleanup for completed runs, permanent deduplication keys and orphaned R2 values.
  • Implement a key-rotation strategy before needing one.
  • Test behavior-changing retained-release rollouts and keep an explicit draining policy.
  • Measure sustained completion throughput under your real step I/O and payload distribution.
  • Review SDK upgrades. This adapter uses private build/runtime integration points and a native VM shim.

The design avoids running your own database server. It does not remove the need to operate the World.

Sources and implementation

Repository links may require access. Vercel links point to public source or published documentation. Logical API names do not establish backend internals.

Browse topics or type to search

IntroductionA Workflow SDK v5 World built on Cloudflare Workers, Durable Objects and R2. Here is what runs where, why each part exists, and what the measurements actually show.Same SDK, different infrastructureA workflow is a log you can replay.Three jobs, kept separateA workflow is a log you can replay.Recorded results, not promisesA workflow is a log you can replay.Read the system in orderA workflow is a log you can replay.The architectureAn ordered store for each run, delivery capacity shared across shards, and execution kept off the queue objects.Where everything livesThe architectureOrder state, distribute executionThe architectureRouting without a global directoryThe architectureWhat the design buys, and costsThe architectureLife of a requestFollow the ordinary static-workflow start path, then the deliveries that turn the stored intent into completed work.Our World: accepting the runLife of a requestOur World: delivering and runningLife of a requestVercel: the corresponding pathLife of a requestWhat a response does and does not guaranteeLife of a requestEvery service, explainedWhat each component owns, why it exists, how it helps, and the limit it introduces. These are logical roles, not twelve separate deployed services.Router Worker and World clientEvery service, explainedRun-store shardsEvery service, explainedQueue shardsEvery service, explainedWorkflow runners and step runnersEvery service, explainedConsumer and retained executor WorkersEvery service, explainedIndex shardsEvery service, explainedHook token registriesEvery service, explainedRun streams and VM snapshotsEvery service, explainedR2 payloads and dead lettersEvery service, explainedAlarms and cron recoveryEvery service, explainedState and deliveryHow an event becomes durable work, why the outbox exists, and where transactions stop.The event is the durable recordState and deliveryWhy commit an outbox?State and deliveryHook claims cross transaction boundariesState and deliveryAt-least-once means side effects can repeatState and deliveryRetries, limits and recoveryState and deliveryExecution and replayWorkflow decisions execute inside a deterministic runtime. Step bodies do the I/O outside it. QuickJS and the native engine trade replay work for memory and compatibility.Workflow code is not step codeExecution and replayQuickJS is our defaultExecution and replayThe native engine uses a build-time shimExecution and replayWhat the replay numbers meanExecution and replayShards and placementSpread independent runs, preserve old routing, and keep state near execution where possible. More shards are capacity, not free speed.Time picks the epoch, hash picks the shardShards and placementA location hint is a hintShards and placementWhy creation throughput is highShards and placementMany runs scale better than one enormous runShards and placementPayloads and byte streamsUse values for control data and byte streams for bulk data. Offloading to R2 removes storage-message pressure, not every memory limit.A value still has to fit in memoryPayloads and byte streamsPass a handle, then move bytes incrementallyPayloads and byte streamsThe producer must outlive the step resultPayloads and byte streamsThe current multi-GiB reader problemPayloads and byte streamsCompared with VercelTwo implementations of the same World contract. We can inspect Vercel’s public adapter, not the internals behind its managed APIs.The services Vercel’s public client usesCompared with VercelThe same jobs, different ownersCompared with VercelHow their transport worksCompared with VercelWhere our design helpsCompared with VercelRead the Vercel limits with their runtime contextCompared with VercelMeasurements and limitsRecorded Workers results, the workload behind each number, and the failures that keep these from being unlimited-capacity claims.Latest regression checkMeasurements and limitsCreation is not completionMeasurements and limitsExecution resultsMeasurements and limitsLimits are not all the same kind of numberMeasurements and limitsKnown failure pointsMeasurements and limitsRun the probesMeasurements and limitsIdentity and deploymentsBindings authorize internal access. Your application protects public routes. Encryption and retained release routing solve separate problems.Internal calls use capabilitiesIdentity and deploymentsEncryption has a narrower scope than “all data”Identity and deploymentsKeep the code that owns old historyIdentity and deploymentsHow Vercel’s identity differsIdentity and deploymentsBuild, deploy and operateThe repository root is an example application. The reusable World lives in packages/world-cloudflare. Deploy the minimal mode first, then add retained executors if you need them.Start with the exampleBuild, deploy and operateKnow which config changes affect old runsBuild, deploy and operateDeploy state first, then the retained executorBuild, deploy and operateTest the adapter, the SDK and the deploymentBuild, deploy and operateOperational work still leftBuild, deploy and operate
Local search. Nothing sent to a server.Esc to close
Documentation