[zsilbi]

Follow-up to #4338 — makes durable object and workflows usable in dev (miniflare runner).

🔗 Linked issue

#4339

❓ Type of change

• 👌 Enhancement (improving an existing functionality like performance)

📚 Description

Compose a dev worker entry that statically re-exports binding-referenced classes from exports.cloudflare.ts (bundled with rolldown) and pass them to env-runner via exports — workerd requires them as static exports, while the app keeps loading through the Vite module runner (HMR intact, DO class changes need a restart - documented).

Forward env/ctx to the app in the dev worker, same as the prod module handler (globalThis.__env__ + req.runtime.cloudflare).

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[vercel]

@zsilbi is attempting to deploy a commit to the Nitro Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds Cloudflare Durable Objects and Workflows support to Nitro through dev-worker composition, Cloudflare runtime binding propagation, documentation, an end-to-end example, and Vite integration tests.

Changes

Cloudflare Durable Objects Integration

Layer / File(s)	Summary
Documentation and user example docs/2.deploy/20.providers/cloudflare.md, examples/cloudflare-durable/*	Documents Durable Object exports, bindings, migrations, runtime access, and restart behavior; adds a working counter example and deployment configuration.
Cloudflare export utilities src/presets/cloudflare/entry-exports.ts, src/presets/cloudflare/utils.ts	Exports the helpers used to resolve Cloudflare exports and read Wrangler configuration.
Dev-worker composition src/presets/cloudflare/dev.ts	Discovers bound Durable Object and Workflow classes, bundles exports, and generates a wrapper that forwards worker lifecycle handlers.
Miniflare and runtime integration src/build/vite/env.ts, src/runtime/internal/vite/dev-worker.mjs	Connects the composed worker to Miniflare and propagates Cloudflare environment and execution context into requests.
Fixture and integration coverage test/examples.test.ts, test/vite/cloudflare-do-fixture/*, test/vite/cloudflare-do.test.ts	Adds Durable Object and Workflow fixtures and verifies counter persistence, environment exposure, and workflow bindings in Vite dev mode.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• nitrojs/nitro#3834: Introduces the Cloudflare exports entry mechanism used by this change.
• nitrojs/nitro#4064: Uses the same Cloudflare runtime binding access path.
• nitrojs/nitro#4338: Touches related Cloudflare local-development runner wiring.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title follows the Conventional Commits format with the feat type and cloudflare scope. It accurately describes the main change: support for Durable Objects, Workflows, and bindings in local de…
Description check	✅ Passed	The description is directly related to the changeset. It explains the dev worker composition, static exports, Miniflare integration, HMR behavior, environment forwarding, linked issue, and documentati…

Full details: Title check

Explanation

The title follows the Conventional Commits format with the feat type and cloudflare scope. It accurately describes the main change: support for Durable Objects, Workflows, and bindings in local development.

Full details: Description check

Explanation

The description is directly related to the changeset. It explains the dev worker composition, static exports, Miniflare integration, HMR behavior, environment forwarding, linked issue, and documentation update.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[socket-security]

No dependency changes detected. Learn more about Socket for GitHub.

👍 No dependency changes detected in pull request

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitro@4341

commit: a546ce5

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/cloudflare-durable/routes/counter.ts`:
- Around line 4-8: The code assumes event.req.runtime?.cloudflare?.env exists
and directly casts it, which will throw a TypeError if missing; update the
handler (defineHandler) to validate that event.req.runtime?.cloudflare?.env is
defined and that env.COUNTER exists before calling
env.COUNTER.getByName("global"), and throw a clear, descriptive error (e.g.,
"Missing Cloudflare Durable Object binding: COUNTER") so callers get an
actionable message instead of a runtime TypeError; reference the env variable
and the COUNTER DurableObjectNamespace/CounterDO binding when adding the checks.

In `@src/presets/cloudflare/dev.ts`:
- Around line 149-153: IPC can call loadDevWorker() before
globalThis.__ENV_RUNNER_UNSAFE_EVAL__ is set, so guard and lazily initialize
that binding instead of dereferencing it; create a small helper (e.g.,
ensureUnsafeEval or createUnsafeEvalBinder) that if
globalThis.__ENV_RUNNER_UNSAFE_EVAL__ is undefined will initialize and assign a
safe fallback object exposing newAsyncFunction (built via the Function
constructor to return import(id) so it behaves like the real binder), then use
that helper when computing devWorkerPromise and in the other block (the similar
166-173 code) so loadDevWorker() never calls undefined.newAsyncFunction;
reference globalThis.__ENV_RUNNER_UNSAFE_EVAL__, devWorkerPromise,
loadDevWorker, newAsyncFunction, devWorkerId, and the ipc.onOpen / ipc.onMessage
pre-load paths when locating where to add the helper and replace direct
dereferences.
- Around line 152-154: The memoized devWorkerPromise (devWorkerPromise) is set
with ??= which leaves a permanently rejected promise on transient import
failures; update the promise chain returned by
newAsyncFunction(...)(devWorkerId) to attach a .catch handler that clears
devWorkerPromise (set it to undefined/null) before rethrowing the error so
subsequent attempts will retry, while keeping the successful .then branch that
sets devWorker; reference devWorkerPromise, devWorker, devWorkerId and the
newAsyncFunction(...).then(...) chain when making the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c8e33f58-1f23-4169-8454-e9ebef5545cd

📥 Commits

Reviewing files that changed from the base of the PR and between 7765bcb and b9506c6.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (23)

• docs/2.deploy/20.providers/cloudflare.md
• examples/cloudflare-durable/README.md
• examples/cloudflare-durable/exports.cloudflare.ts
• examples/cloudflare-durable/index.html
• examples/cloudflare-durable/nitro.config.ts
• examples/cloudflare-durable/package.json
• examples/cloudflare-durable/routes/counter.ts
• examples/cloudflare-durable/server/durable/counter.ts
• examples/cloudflare-durable/tsconfig.json
• examples/cloudflare-durable/vite.config.ts
• examples/cloudflare-durable/wrangler.jsonc
• src/build/vite/env.ts
• src/presets/cloudflare/dev.ts
• src/presets/cloudflare/entry-exports.ts
• src/presets/cloudflare/utils.ts
• src/runtime/internal/vite/dev-worker.mjs
• test/examples.test.ts
• test/vite/cloudflare-do-fixture/durable/counter.ts
• test/vite/cloudflare-do-fixture/durable/entrypoint.ts
• test/vite/cloudflare-do-fixture/exports.cloudflare.ts
• test/vite/cloudflare-do-fixture/routes/counter.ts
• test/vite/cloudflare-do-fixture/vite.config.ts
• test/vite/cloudflare-do.test.ts

[pi0x]

Rebased this onto latest main locally — it applies cleanly, only line offsets. I could not push the rebased branch from my environment, so the branch here is untouched.

One real bug found: the example's wrangler.jsonc has trailing commas (our formatter adds them), and readWranglerConfig parses .json/.jsonc with confbox's parseJSONC, which rejects trailing commas. So vite dev crashes on startup in the new example. Switching those two parsers to parseJSON5 fixes it; I added a unit test for it.

Otherwise the dev-worker composition and the DO/workflow tests look good. Note this overlaps with #3875 (durable binding names) and #3238 (wrangler env) — worth landing this one first.

This comment was written by an AI assistant on behalf of the Nitro maintainers. Please double-check anything that looks wrong.

[pi0]

Hi. Thanks for PR and sorry for late reply.

#4677 should already cover objective of this. Lets merge via it.