nitrojs / nitrojs/nitro

Feature Request: Native Cloudflare Durable Objects binding support in Nitro

Open
#4,583 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

v3
Dominant language
TypeScript
Stars
11.2k
Forks
899
Avg merge
2d 24m
Merged PRs (30d)
40

Description

Feature Request

Problem

Nitro's Cloudflare Pages/Workers preset is excellent, but there's currently no native binding type for Cloudflare Durable Objects in Nitro's runtime context. When building stateful edge apps (WebSockets, rate limiting, collaborative features), developers have to manually cast env to access Durable Objects, losing type safety.

Current workaround
// nuxt.config.ts — no native DO type support
export default defineNuxtConfig({
  nitro: {
    cloudflare: {
      // no `durableObjects` binding config here
    }
  }
})

// server/api/room.ts — manual unsafe cast
export default defineEventHandler((event) => {
  const env = event.context.cloudflare?.env as any
  const id = env.ROOMS.idFromName('main')  // no type safety
  const stub = env.ROOMS.get(id)
  return stub.fetch(event.node.req)
})
Proposed Solution

Add a durableObjects field to Nitro's Cloudflare binding configuration, similar to how KV / R2 / D1 are handled:

// nitro.config.ts
export default defineNitroConfig({
  cloudflare: {
    bindings: {
      kvNamespaces: ['KV'],
      r2Buckets: ['BUCKET'],
      d1Databases: ['DB'],
      durableObjects: ['ROOMS'],  // ← new
    }
  }
})

This would:

  1. Auto-generate typed H3Event.context.cloudflare.env.ROOMS bindings
  2. Work with wrangler.toml [[durable_objects.bindings]] declarations
  3. Enable Miniflare simulation in local dev via wrangler dev
Environment
  • Nitro: 2.9.x
  • Deployment target: cloudflare-pages
  • Use case: real-time collaborative app with WebSocket hibernation API

Would be happy to contribute a PR with this feature if the approach looks good.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing Nitro’s existing KV, R2, and D1 Cloudflare binding configuration and how it produces typed H3Event.context.cloudflare.env values. Compare the proposed durableObjects entry with wrangler.toml declarations and the cloudflare-pages preset. Done means the ROOMS binding is typed, compatible with Wrangler Durable Objects declarations, and usable in local wrangler dev simulation.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design, cloud
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.