OpenAICloudflare Developer PlatformJul 4, 2026, 12:00 AM

Durable Objects, Workers - Declare Durable Object class lifecycle with `exports`

A condensed section focused on the key takeaways first.

Original Post

Quick Digest

Summary

A condensed section focused on the key takeaways first.

openaienmodel: gpt-5-mini-2025-08-07

Declare Durable Object class lifecycle with exports

Key Points

  • Declarative exports replace migrations
  • Zero-downtime renames and transfers
  • Cross-Worker safety checks during deploy

Summary

A new declarative exports field in your Wrangler configuration replaces the legacy migrations array for managing Durable Object class lifecycle. Instead of ordering tagged migration steps, declare each Durable Object class in an exports map keyed by class name and set its lifecycle state (defaults to created). Wrangler diffs this map against the deployed state and performs create/rename/delete/transfer operations, reporting structured deployment output.

Key Points

  • Use a top-level exports map in wrangler config keyed by class name instead of an ordered migrations list. Example: "Room": {"type":"durable-object","storage":"sqlite"} and "ChatRoom": {"type":"durable-object","state":"renamed","renamed_to":"Room"}.
  • Supported states: created (default), deleted, renamed, transferred, and expecting-transfer (receiver for cross-Worker transfers).
  • No migration tags or historical chain; the current exports map is the single source of truth and Wrangler surfaces structured diffs on deploy (creates, updates, deletes, renames, transfers, and stale entries).
  • Zero-downtime patterns are first-class: tombstones allow three-deploy renames and four-deploy cross-Worker transfers without runtime errors during rollout.
  • Cross-Worker safety: Wrangler lists other Workers that still reference a namespace when you plan to delete or rename it so you can redeploy them before the change goes live.
  • Backwards compatible: existing Workers using migrations continue to work; exports and migrations cannot be used together in the same Worker.
  • Migration checklist for engineers: convert your migrations to an exports map, remove migrations from the Worker, deploy, review Wrangler's structured output, and redeploy any Workers listed as referencing renamed/deleted namespaces.

Full Translation

Translations

A translation section that keeps the flow of the original article.

No translations yet.