Skip to content

[wrangler] Add experimental support for declarative Durable Object exports#14210

Draft
petebacondarwin wants to merge 3 commits into
cloudflare:mainfrom
petebacondarwin:pbacondarwin/devx-2572-wrangler-do-exports
Draft

[wrangler] Add experimental support for declarative Durable Object exports#14210
petebacondarwin wants to merge 3 commits into
cloudflare:mainfrom
petebacondarwin:pbacondarwin/devx-2572-wrangler-do-exports

Conversation

@petebacondarwin
Copy link
Copy Markdown
Contributor

Fixes DEVX-2572.

Adds client-side wiring for the EWC declarative Durable Object exports flow.

What this adds

A new declarative exports map in wrangler.json / wrangler.toml as an alternative to the legacy migrations array, gated behind --experimental-do-exports (alias --x-do-exports):

{
	"exports": {
		"MyDO": { "type": "durable_object", "storage": "sqlite" },
		"OldGone": { "type": "deleted" },
		"OldName": { "type": "renamed", "renamed_to": "NewName" },
		"Movee": { "type": "transferred", "transferred_to_script": "target-worker" }
	}
}

Both wrangler deploy and wrangler versions upload send the new payload when the flag is on. The upload response's exports_reconciliation envelope is rendered with the spec's visibility hierarchy:

  • errors → red per-class detail (rendered from the v4 envelope's meta.details[]), thrown as a UserError so every blocking scenario surfaces in one round trip
  • warnings → yellow, prominent (reserved — no current server scenarios emit one)
  • info → dim text, with per-entry blocked_by lists for stale tombstones
  • removable_entries → single-line "you can delete these from exports" hint

Server dependencies

Requires the exports_reconciliation account entitlement on Cloudflare's side. Hidden behind an experimental flag until that gate ships broadly.

Server-side phases: DEVX-2563 (1a), DEVX-2598 (1b), DEVX-2564 (2), DEVX-2600 (1d). DEVX-2599 (1c) adds full transferred support — until that lands, the transferred tombstone returns a "not yet implemented" error from EWC, which is rendered correctly via the same meta.details path.

Coordinated with the new config redesign

The new @cloudflare/config package's exports.durableObject() is extended with tombstone factories (exports.deleted(), exports.renamed({ to }), exports.transferred({ toScript })) and a transferFrom option. The previous "Durable Object exports are not currently supported" throw in convertExports is replaced with a snake_case conversion that emits the wrangler config schema.

Spec

https://wiki.cfdata.org/spaces/WX/pages/1396640001


  • Tests
    • Tests included/updated
    • Automated tests not possible - manual testing has been completed as follows:
    • Additional testing not necessary because:
  • Public documentation
    • Cloudflare docs PR(s):
    • Documentation not necessary because: customer-facing docs are tracked separately in DEVX-2569.

A picture of a cute animal (not mandatory, but encouraged)

…ports

Adds client-side wiring for the EWC declarative DO exports flow (DEVX-2572).
Gated behind --experimental-do-exports (alias --x-do-exports). Wires the
new field through both `wrangler deploy` and `wrangler versions upload`,
renders the success-side reconciliation envelope (created / updated /
deleted / renamed / transferred / transfer_pending / info / warnings /
removable_entries), and converts the EWC `ErrExportsReconciliation`
error envelope's `meta.details[]` into a structured UserError so the
deploy command surfaces every blocking scenario in one round trip.

Also extends the new @cloudflare/config package's `exports.durableObject()`
with tombstone factories (`deleted()`, `renamed()`, `transferred()`) and
a `transferFrom` option, and replaces the previous `convertExports`
throw with a snake_case conversion that maps to the wrangler config
schema.

Spec: https://wiki.cfdata.org/spaces/WX/pages/1396640001
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Jun 5, 2026

🦋 Changeset detected

Latest commit: be1facc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages
Name Type
wrangler Minor
@cloudflare/vite-plugin Patch
@cloudflare/vitest-pool-workers Patch
@cloudflare/wrangler-bundler Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented Jun 5, 2026

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@14210

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@14210

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@14210

miniflare

npm i https://pkg.pr.new/miniflare@14210

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@14210

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@14210

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@14210

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@14210

@cloudflare/workers-auth

npm i https://pkg.pr.new/@cloudflare/workers-auth@14210

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@14210

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@14210

wrangler

npm i https://pkg.pr.new/wrangler@14210

@cloudflare/wrangler-bundler

npm i https://pkg.pr.new/@cloudflare/wrangler-bundler@14210

commit: be1facc

DEVX-2572 replaces the "Durable Object exports are not currently
supported" throw in @cloudflare/config's convertExports with a
snake_case conversion. Update the experimental-new-config spec to
assert that resolvePluginConfig now succeeds rather than throws.
…s e2e

Restructure the gated DEVX-2572 e2e suite into four self-contained
describe blocks, each owning its own helper / worker(s) and afterAll
cleanup so stateful deploy sequences can't bleed across blocks:

  - wrangler deploy           — keeps the existing scenarios 1, 2, T2,
                                T3, and 5 (auto-provision, no-op,
                                delete tombstone, stale tombstone, and
                                the 100402 multi-error envelope).
  - wrangler versions upload  — exercises the same payload and
                                reconciliation rendering on the
                                POST /versions path.
  - zero-downtime rename      — three deploys covering the live target
                                + renamed tombstone shape and the
                                no-op drop of the tombstone.
  - cross-script transfer     — two-script, two-phase commit covering
                                target-side transfer_from -> Transfer
                                pending, then source-side transferred
                                -> Transferred (committed).

Still gated behind WRANGLER_E2E_DO_EXPORTS=1 + CLOUDFLARE_ACCOUNT_ID so
the suite stays inert in CI until the server-side exports_reconciliation
entitlement is enabled.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Untriaged

Development

Successfully merging this pull request may close these issues.

2 participants