Support separating Durable Objects into a dedicated Worker to enable Preview URLs

[devin-ai-integration]

Is your feature request related to a problem?

Currently, Workers that export Durable Object classes cannot use Preview URLs. When using doQueue (the DOQueueHandler Durable Object for ISR revalidation deduplication) or doShardedTagCache (the DOShardedTagCache Durable Object), the OpenNext build bundles these DO classes into the main app Worker. This means the app Worker exports DO classes and is therefore ineligible for Cloudflare's preview URL feature.

Preview URLs are valuable for CI/CD workflows, PR previews, and staging environments, but are currently unavailable to any OpenNext app that uses DO-based queue or tag cache.

Describe the solution you'd like

Support an option (e.g., externalDurableObjects: true in open-next.config.ts or defineCloudflareConfig()) that separates the Durable Object classes (DOQueueHandler, DOShardedTagCache) into a dedicated standalone Worker during the build.

The main app Worker would reference the DOs via script_name in its wrangler config:

"durable_objects": {
  "bindings": [
    { "name": "NEXT_CACHE_DO_QUEUE", "class_name": "DOQueueHandler", "script_name": "my-app-dos" },
    { "name": "NEXT_TAG_CACHE_DO_SHARDED", "class_name": "DOShardedTagCache", "script_name": "my-app-dos" }
  ]
}

Since the app Worker would no longer export any DO classes, it would be eligible for preview URLs.

This pattern is already proven in the multi-worker setup, where the "server" Worker references DOs in the "middleware" Worker using script_name. The difference here is a simpler variant: a small DO-only Worker alongside the main app Worker, without the full middleware/server split.

Ideally, the @opennextjs/cloudflare build and deploy commands would:

1. Generate a separate DO Worker with just the DO class exports and its own wrangler config (including migrations).
2. Generate the main app Worker's wrangler config with script_name references to the DO Worker.
3. Deploy the DO Worker first, then the app Worker.

Describe alternatives you've considered

• Manual multi-worker setup: The existing multi-worker approach can work, but it explicitly states it is incompatible with preview URLs (because the middleware ingress Worker still exports the DOs). It also requires manual deployment orchestration and cannot use @opennextjs/cloudflare deploy.
• Manually splitting the DO Worker: Users could manually create a separate Worker project for the DOs, but this requires understanding the build output paths, maintaining separate wrangler configs, and coordinating deployments — significant operational overhead.
• Avoiding DOs entirely: Using in-memory deduplication instead of doQueue, but this loses cross-isolate deduplication and is less robust.

@opennextjs/cloudflare version

Latest

Additional context

• Cloudflare preview URL limitation docs: https://developers.cloudflare.com/workers/configuration/previews/#limitations
• Wrangler script_name docs for external DO bindings: https://developers.cloudflare.com/workers/wrangler/configuration/#durable-objects
• Related multi-worker approach: https://opennext.js.org/cloudflare/howtos/multi-worker

Before submitting

• I have checked that there isn't already a similar feature request
• This is a single feature (not multiple features in one request)

[conico974]

It is already supported, just not documented yet. I made such an implementation here https://github.com/GitbookIO/gitbook/tree/main/packages%2Fgitbook%2FopenNext%2FcustomWorkers
It has 3 workers, one for hosting all the DO's one for the middleware and one for the rest

[alex-all3dp]

I also got that setup to work. See opennextjs/docs#211 . Maybe @conico974 @vicb you could take a look at that PR if you find the time and possibly get it merged if the setup and docs look good enough? 😊 Would love to get some feedback on it, also to see if we are missing or misconfiguring anything on our end