[Durable Objects] Document class exports

[petebacondarwin]

Summary

Rewrites the Durable Objects class lifecycle reference around declarative exports, while preserving the legacy migrations array documentation on a separate page.

• Documents the JSONC exports schema, tombstone states, reconciliation output, storage rules, zero-downtime rename flow, and cross-Worker transfer flow.
• Updates Wrangler configuration, Durable Objects get-started, Agents configuration, versions/deployments constraints, release notes, and shared partial links to reflect the new flow.
• Adds a Durable Objects changelog entry for the new declarative class lifecycle configuration.

Screenshots (optional)

Documentation checklist

• Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.
• The change adheres to the documentation style guide.
• If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.

[cloudflare-docs-bot]

Review

⏸️ Automatic reviews for this PR are paused.

This PR has already received 2 automatic reviews. To run another review, a codeowner can comment /review or /full-review. To permanently lift the limit for this PR, a codeowner can comment /ignore-review-limit.

Tip: Keep PRs in draft mode until they are ready for review — the bot skips draft PRs automatically.

---

⚠️ 14 warnings, 💡 13 suggestions found in full PR diff.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Warnings (4)

File	Issue
durable-objects/reference/durable-objects-migrations.mdx line 510	Inconsistent error scenario name — The reconciliation sample (line 406) and zero-downtime rename guidance (line 249) emit the info tag tombstone_class_still_in_code, but the error reference table lists the scenario as tombstone_delete_class_still_in_code. A renamed tombstone cannot match a delete-specific tag, so one of the names is wrong. Fix: Confirm the actual API/CLI scenario tag and align the table row, the rename guidance, and the reconciliation sample so they all use the same identifier.
durable-objects/reference/durable-object-class-migrations-legacy.mdx line 388	Invalid JSONC placeholder syntax — The wrangler.jsonc example contains "migrations": [{ ... }]. The ... inside an array/object literal is not valid JSON/JSONC syntax and will fail if a reader copies the snippet. Fix: Replace { ... } with a concrete migration object or use a comment to indicate a placeholder, e.g. [{ /\* your migration here \*/ }].
durable-objects/reference/durable-object-class-migrations-legacy.mdx line 392	Invalid JSONC placeholder syntax — The same example contains "migrations": [{...}] for the staging override, which is also invalid JSONC syntax. Fix: Replace {...} with a concrete migration object or a comment placeholder.
workers/wrangler/configuration.mdx line 713	Invalid configuration example — The renamed export example for OldName sets renamed_to: "NewName", but NewName does not appear as an entry in the same exports map. The same section states the destination class name must appear as a live entry in the same exports map. Fix: Add a NewName live entry to the example exports map, for example {"type": "durable-object", "storage": "sqlite"}.

Style Guide Review

Warnings (10)

File	Issue
durable-objects/reference/durable-objects-migrations.mdx line 490	Table introduction must be a complete sentence ending in a colon — "Allowed and forbidden fields for each state:" is a sentence fragment before a table Fix: Introduce the table with a complete sentence ending in a colon, e.g. "The following table lists the allowed and forbidden fields for each state:"
durable-objects/reference/durable-objects-migrations.mdx line 502	Table introduction must be a complete sentence ending in a colon — "When a deploy fails reconciliation, Cloudflare returns one error per class..." ends with a period before the error-reference table Fix: End the introductory sentence with a colon instead of a period
durable-objects/reference/durable-object-class-migrations-legacy.mdx line 175	Remove spaces around equals in component props — <Details header = \"Delete migration example\"> Fix: Change to <Details header=\"Delete migration example\">.
durable-objects/reference/durable-object-class-migrations-legacy.mdx line 248	Remove spaces around equals in component props — <Details header = \"Rename migration example\"> Fix: Change to <Details header=\"Rename migration example\">.
durable-objects/reference/durable-object-class-migrations-legacy.mdx line 336	Remove spaces around equals in component props — <Details header = \"Transfer migration example\"> Fix: Change to <Details header=\"Transfer migration example\">.
durable-objects/reference/durable-object-class-migrations-legacy.mdx line 398	No duplicate words — Line contains Migrations at at the environment-level Fix: Remove the duplicate at: Migrations at the environment-level....
durable-objects/reference/durable-object-class-migrations-legacy.mdx line 175	Heading formatting / component prop — <Details header = \"Delete migration example\"> uses sentence case; prop spacing not covered by explicit loaded rules. Fix: Review the use of spaces around the equals sign and ensure component attributes follow standard formatting.
workers/wrangler/configuration.mdx line 1913	WranglerConfig input must be TOML — WranglerConfig block uses ```jsonc as input. Fix: Use ```toml inside <WranglerConfig>; JSON output is generated automatically.
durable-objects/best-practices/rules-of-durable-objects.mdx line 1570	WranglerConfig component requires TOML input — Added JSONC content inside <WranglerConfig> (lines 1570–1578); the component expects TOML input and auto-generates JSON output. Fix: Rewrite the Wrangler config snippet as TOML inside <WranglerConfig> instead of providing JSONC input.
durable-objects/get-started.mdx line 290	WranglerConfig: TOML input required; JSON auto-generated — Added JSONC object ("exports": { ... }) inside <WranglerConfig> Fix: Provide the Wrangler config as TOML inside <WranglerConfig>; JSON output is generated automatically

Suggestions (13)

File	Issue
durable-objects/reference/durable-objects-migrations.mdx line 71	Avoid semicolons joining two independent clauses — "The class name remains the same; the value tells Cloudflare what to do with the existing namespace" joins independent clauses with a semicolon Fix: Split into two sentences
durable-objects/reference/durable-objects-migrations.mdx line 177	Consider writing short bullet lists as prose — The "A deleted tombstone has two preconditions" list contains only two bullet items Fix: Rewrite the two preconditions as prose
durable-objects/reference/durable-objects-migrations.mdx line 186	Consider writing short bullet lists as prose — The "Renaming requires:" list contains only two bullet items Fix: Rewrite the two rename requirements as prose
durable-objects/reference/durable-objects-migrations.mdx line 387	Consider writing short bullet lists as prose — The "Live entries must declare a storage value" list contains only two bullet items Fix: Rewrite the two storage options as prose
durable-objects/reference/durable-objects-migrations.mdx line 429	Use 'refer to [link]' instead of 'see the [link]' — "See the error reference for the full list of error scenarios" uses 'see the' before a link Fix: Change to "refer to the error reference"
durable-objects/reference/durable-object-class-migrations-legacy.mdx line 49	Use active voice / sentence case headings — Section heading ## Create migration and similar bare imperative heading. Fix: No direct rule violated; consider whether a more descriptive heading is needed.
changelog/durable-objects/2026-06-30-declarative-do-class-exports.mdx line 36	Links — avoid see the [link] — Line uses see the [migration guide] Fix: Replace with refer to the [migration guide]
workers/configuration/versions-and-deployments/gradual-deployments.mdx line 197	Passive voice — Versions ... cannot be uploaded Fix: Rewrite in active voice, e.g. 'You cannot upload versions ...'
workers/configuration/versions-and-deployments/gradual-deployments.mdx line 197	Passive voice — Once a lifecycle change is deployed Fix: Rewrite in active voice, e.g. 'Once you deploy a lifecycle change'
workers/configuration/versions-and-deployments/gradual-deployments.mdx line 199	Passive voice — can be deployed with the following command Fix: Rewrite in active voice, e.g. 'Deploy ... with the following command'
workers/configuration/versions-and-deployments/gradual-deployments.mdx line 203	Passive voice — should be deployed independently of other code changes Fix: Rewrite in active voice, e.g. 'Deploy ... independently of other code changes'
workers/configuration/versions-and-deployments/gradual-deployments.mdx line 205	Passive voice — If a delete were applied / would have been deleted Fix: Rewrite in active voice, e.g. 'If you deleted ...'
workers/configuration/versions-and-deployments/gradual-deployments.mdx line 207	Passive voice — would have to have already been rolled out Fix: Rewrite in active voice, e.g. 'you must have already rolled out ...'

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.

[petebacondarwin]

/review

[petebacondarwin]

/review

[petebacondarwin]

/full-review

[irvinebroque]

@iglesiasbrandon

[iglesiasbrandon]

/bonk review this pr

[ask-bonk]

This is a well-structured rewrite of the Durable Object lifecycle docs. The new exports-first flow is much clearer than the imperative migrations model, and preserving the legacy reference on its own page is the right call.

A couple of issues to fix before merging:

1. Inconsistent error scenario tag — The prose and reconciliation sample use tombstone_class_still_in_code, but the error reference table lists tombstone_delete_class_still_in_code. These need to be aligned.
2. Tab indentation in the transfer section — Step 3 of the cross-Worker transfer flow uses tab characters instead of 4 spaces for indentation. In Markdown/MDX, tab-indented lines after a blank line can render as <pre> code blocks rather than normal prose or component children, which breaks the <Steps> layout.

Everything else looks solid.

[ask-bonk]

The reconciliation sample (line 406) and rename guidance (line 249) emit the generic info tag tombstone_class_still_in_code, but this table row uses tombstone_delete_class_still_in_code. Since the sample explicitly shows this tag for a renamed tombstone, the table should use the generic name and a matching description.

Suggested change

	| `tombstone_delete_class_still_in_code` | A `deleted` tombstone names a class that is still exported in code. | Remove the class from your code first, then deploy the tombstone. |
	| `tombstone_class_still_in_code` | A tombstone names a class that is still exported in code. | Remove the class from your code first, then deploy the tombstone. |

[ask-bonk]

This block (and the surrounding lines in step 3) is indented with tab characters instead of 4 spaces. In Markdown/MDX, tab-indented lines after a blank line can render as <pre> code blocks rather than normal prose or component children, which breaks the <Steps> layout. Please convert the tabs to 4 spaces to match the rest of the step.

[ask-bonk]

Review submitted for PR #31650.

What I reviewed

• The full diff across 18 files, focusing on the new exports-based Durable Object lifecycle docs and the legacy migrations preservation.
• Key files: durable-objects-migrations.mdx, durable-object-class-migrations-legacy.mdx, workers/wrangler/configuration.mdx, and the Agents configuration updates.

Feedback posted
Two blocking issues to fix before merge:

1. Inconsistent error scenario tag (durable-objects-migrations.mdx line 510)
   The prose and reconciliation sample use tombstone_class_still_in_code, but the error reference table lists tombstone_delete_class_still_in_code. Since the sample explicitly shows this tag for a renamed tombstone, the table should use the generic name.

2. Tab indentation in the transfer section (durable-objects-migrations.mdx lines 328–348)
   Step 3 of the cross-Worker transfer flow uses tabs instead of 4 spaces. In MDX, tab-indented lines after a blank line can render as <pre> code blocks, breaking the <Steps> layout.

Everything else looks solid — the structure is clean, links are consistent, and the decision to keep legacy docs on a separate page is the right one.

github run