sincecutoff.com
/v1/json /v1/md llms.txt
← all changes

wrangler deploy declares Durable Object lifecycle with exports

Introduced 2026-07-02 · score 0.97

HOW TO USE IT

When declaring Durable Object class lifecycle in Wrangler config, use `exports` entries keyed by class name and deploy with `wrangler deploy`.

npx wrangler deploy

WHY THIS HELPS

Declare Durable Object lifecycle changes and use the declarations in deployment, local development, tests, and generated types.

BEFORE THIS CHANGE

The release note describes `migrations` as the legacy imperative alternative to declarative `exports`.

REQUIREMENTS AND LIMITATIONS

  • Version: 4.107.0
  • exports.<Class>.type (required): Set to `"durable-object"` for a Durable Object class entry.
  • exports.<Class>.state: Lifecycle state: `created` (default), `deleted`, `renamed`, `transferred`, or `expecting-transfer`.
  • exports.<Class>.storage (required): Required for `created` or `expecting-transfer`; use `sqlite` for new namespaces.
  • exports.<Class>.renamed_to (required): For `renamed`, names the destination class, which must also be a live entry in `exports`.
  • exports.<Class>.transferred_to (required): For `transferred`, names the target Worker.
  • exports.<Class>.transfer_from (required): For `expecting-transfer`, names the source Worker.
  • Prerequisite: Declare the class in Worker code and export it; add a `durable_objects.bindings` entry if the Worker needs to access it through `env`.
  • Prerequisite: For newly created namespaces, use `storage: "sqlite"`; `legacy-kv` is accepted only for already provisioned key-value namespaces.
  • `type` is currently always `"durable-object"`.
  • The `state` field defaults to `"created"` (live) when omitted.
  • An actor binding (`durable_objects.bindings`) to a class declared only in `exports` on the same `wrangler versions upload` is rejected with error code 100406 because the binding cannot resolve until the namespace is provisioned.
  • For that version upload constraint, stage the class via `ctx.exports.X` without a binding and add the binding at deploy time, or use `wrangler deploy` to provision and bind in one step; the same constraint applies to the `migrations` flow.
  • Multi-version percentage deploys with selected versions that disagree on declarative `exports` are rejected; deploy the version that changes `exports` at 100% first, then run the percentage-split deploy. Single-version (100%) deploys are unaffected.
  • Docs conflict: The current Durable Object docs say `wrangler versions upload` fails when the configuration contains `exports`, and that lifecycle changes apply only through `wrangler deploy`; this differs from the supplied v4.107.0 release note, which says upload forwards `exports` and reconciliation occurs at version deploy or `wrangler deploy`. https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/
  • Docs conflict: The current docs say gradual deployments are unsupported with `exports`; this differs from the supplied release note's percentage-split deployment guidance. The current docs are newer than v4.107.0. https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card