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]

📝 Walkthrough

Walkthrough

Adds configurable Durable Object binding name for Cloudflare via a new cloudflare.durable.bindingName option, injects import.meta._durableBindingName at build time, reads it at runtime to resolve the binding name, updates wrangler durable_objects bindings, and adds tests and a fixture for a custom binding name.

Changes

Cohort / File(s)	Summary
Type definitions src/types/global.ts, src/presets/cloudflare/types.ts	Added NitroImportMeta._durableBindingName?: string and CloudflareOptions.durable?: { bindingName?: string }.
Build configuration src/build/config.ts	Injected _durableBindingName into importMetaInjections in baseBuildConfig, sourcing nitro.options.cloudflare?.durable?.bindingName or "$DurableObject".
Runtime implementation src/presets/cloudflare/runtime/cloudflare-durable.ts	DURABLE_BINDING now resolves from import.meta._durableBindingName (fallback "$DurableObject"); binding lookups, stub retrieval, and websocket wiring use the resolved name.
Wrangler config generation src/presets/cloudflare/utils.ts	When cfTarget is "module", ensures wranglerConfig.durable_objects.bindings contains a Durable Object binding with the configured bindingName, avoiding duplicate class_name entries.
Tests & fixtures test/presets/cloudflare-durable.test.ts, test/fixture/nitro.config.ts	Added fixture setting cloudflare.durable.bindingName = "MyCustomDO" and tests asserting the built server entry references the custom binding name and that the server index exports the $DurableObject symbol where expected.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review flow from build injection → runtime read → wrangler config generation for consistent fallback to "$DurableObject".
• Verify typing and injection of import.meta._durableBindingName.
• Check tests correctly validate both custom and default binding-name behavior.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows conventional commits format with 'feat' prefix and clearly describes the main change: adding a durable.bindingName config option to Cloudflare preset.
Description check	✅ Passed	The description clearly explains the purpose, changes, usage examples, and related issues. It directly relates to the changeset modifications across all affected files.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

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

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

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

📒 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

🔇 Additional comments (1)

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

332-347: LGTM! Previous critical and major issues have been resolved.

The implementation correctly addresses both previously flagged concerns:

1. Bindings array initialization (line 337): Now explicitly ensures bindings is always an array before any operations, preventing the silent no-op that would occur if durable_objects existed without a bindings property.

2. Binding validation (lines 338-340): Now checks both name === bindingName AND class_name === "$DurableObject", preventing misconfigurations where a user's manually configured binding has the correct class but wrong name.

The logic correctly handles all scenarios: creating config from scratch, initializing missing bindings array, skipping duplicate bindings, and adding new bindings when needed.

---

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.}

[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?