feat(cloudflare): add durable.bindingName config

[onmax]

Summary

Adds cloudflare.durable.bindingName config option to customize the Durable Object binding name used by defineWebSocketHandler.

Before: Hardcoded $DurableObject binding name
After: Configurable via nitro.cloudflare.durable.bindingName

Changes

1. New config option cloudflare.durable.bindingName (default: $DurableObject)
2. Auto-generates durable_objects in wrangler.json when deployConfig: true

Usage

// nitro.config.ts
export default defineNitroConfig({
  preset: "cloudflare_durable",
  cloudflare: {
    deployConfig: true,
    durable: {
      bindingName: "MyDO"
    }
  }
})

With deployConfig: true, wrangler.json auto-includes:

{
  "durable_objects": {
    "bindings": [{ "name": "MyDO", "class_name": "$DurableObject" }]
  }
}

Reproduction

Reproduction with pnpm patch: https://github.com/onmax/repros/tree/main/nitro-3378

git clone --depth 1 --filter=blob:none --sparse https://github.com/onmax/repros.git
cd repros
git sparse-checkout set nitro-3378
cd nitro-3378
pnpm i
pnpm build
pnpm preview

Related

• cloudflare_durable WebSockets broken in preview; cloudflare_module inconsistent on Workers nuxt-hub/core#722
• Support for Custom Cloudflare Durable Objects with cloudflare_durable preset #3378

[vercel]

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

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0701b07a-b6d9-4d77-a63b-6917648567b2

📥 Commits

Reviewing files that changed from the base of the PR and between 3997415 and 0196465.

📒 Files selected for processing (3)

• docs/2.deploy/20.providers/cloudflare.md
• src/build/virtual/_all.ts
• src/build/virtual/cloudflare-durable.ts

---

📝 Walkthrough

Walkthrough

This change introduces Cloudflare Durable Objects support to Nitro by adding configuration options for custom binding names, runtime resolution logic, build-time template generation, and supporting utilities. The implementation spans type definitions, runtime bindings, virtual module generation, and related tests and documentation.

Changes

Cohort / File(s)	Summary
Type & Configuration src/presets/cloudflare/types.ts, src/presets/cloudflare/utils.ts	Added optional durable configuration block to CloudflareOptions with bindingName field. Extended writeWranglerConfig to populate Durable Objects bindings in wrangler.json based on configured binding name.
Runtime Durable Integration src/presets/cloudflare/runtime/cloudflare-durable.ts	Modified DURABLE_BINDING constant to conditionally resolve from import.meta._durableBindingName with fallback to "$DurableObject", enabling custom binding name support at runtime.
Build Virtual Modules src/build/virtual/_all.ts, src/build/virtual/cloudflare-durable.ts	Added new virtual module cloudflare-durable.ts that generates Durable Objects configuration and optional resolver export. Integrated module into virtual templates pipeline in _all.ts.
Testing & Documentation test/presets/cloudflare-durable.test.ts, docs/2.deploy/20.providers/cloudflare.md	Added comprehensive test suite verifying custom binding names and default exports. Added documentation section explaining Durable Objects configuration, resolver implementation, and usage examples.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows conventional commits format with 'feat' type and descriptive scope. It accurately summarizes the main change: adding a new durable.bindingName configuration option.
Description check	✅ Passed	The description is well-related to the changeset, providing a clear summary of changes, usage examples, and links to related issues. It effectively explains the before/after behavior and configuration options.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

📝 Coding Plan

• Generate coding plan for human review comments

---

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 and usage tips.}

Tip

CodeRabbit can use Trivy to scan for security misconfigurations and secrets in Infrastructure as Code files.

Add a .trivyignore file to your project to customize which findings Trivy reports.

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5815b80 and b2d4ad7.

📒 Files selected for processing (1)

• src/presets/cloudflare/utils.ts (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-12-03T19:09:13.905Z

Learnt from: medz
Repo: nitrojs/nitro PR: 3834
File: src/presets/cloudflare/server-entry.ts:63-63
Timestamp: 2025-12-03T19:09:13.905Z
Learning: In the Nitro Cloudflare preset (src/presets/cloudflare/server-entry.ts), native errors from oxc-parser and Node.js readFile operations should be allowed to bubble up naturally without wrapping, as their native error messages are more user-friendly and provide better diagnostic information.

Applied to files:

• src/presets/cloudflare/utils.ts

[franklin-tina]

Question about this (and maybe the current implementation of Durable Objects via the cloudflare-durable preset):
Does this mean we can only have one Durable Object in the Nuxt app?

[Abdulla060]

The current implementation of the cloudflare_durable preset hard codes the durable object instance id to the value server. The line in question is

nitro/src/presets/cloudflare/runtime/cloudflare-durable.ts

Line 12 in ba5147a

const DURABLE_INSTANCE = "server";

This causes the entire app to shares a single DurableObject instance. Cloudflare recommends a coordination server that manages multiple DurableObject instances since each DurableObject can only handle about 1000 requests/s see.

I believe there should also be a way to pass the instance name. In the config, the user should be able to enable/disable this feature.

[Abdulla060]

@onmax Thank you very much for your work on this!

After reviewing the implementation, I have some concerns regarding how closely it aligns with the Nitro/Nuxt architecture. Specifically, I'm worried that consolidating all DO instance selection into a single file might become a bottleneck.

The following PR #181 has just been made to crossws which will enable the functionality described in here. This approach allows each route to handle its own DO selection independently and eliminates the need for external file loading, which feels a bit cleaner for this use case.