fix(void): restore Container Durable Object bindings in the dev server (#696)

Since 1.5.0, an app that uses `void/sandbox` can't reach its Sandbox in
the dev server. `getSandbox()` throws:

```
env: Missing Cloudflare binding 'SANDBOX'.
```

Other Container classes lose their binding too. 1.4.0 works.

Since 8b26dba, the config for `@cloudflare/vite-plugin` 2.0 comes from
`migrateBuiltWranglerConfig()`, which rewrites the binding of each
Container class as `unsafe:durable_object_namespace`. That form is only
for the Worker upload. Miniflare skips unsafe bindings that have no dev
plugin, so the class and its Container still exist in dev, but `env` has
no binding for them.

## Fix

In serve, `void:cloudflare-config` turns these bindings back into
regular `durable-object` bindings. Builds and deploys keep the unsafe
form.

Only the generated binding of a Container class changes. An unsafe
binding in the user's config has the same type, but it may point at
another Worker, even at a class with the same name as a local Container.
Turning it into a local binding would connect it to the local class
instead, or stop workerd from starting if this Worker has no such class.

`docs/guide/sandboxes.md` already describes local development with
Docker, so the docs do not change.

## Not fixed here

These also regressed in 1.5.0:

- `vite preview` with a Sandbox fails with the same error.
- A Container with a Dockerfile `image` outside `void/sandbox` stops the
dev server from starting.
- A Container in an auxiliary Worker stops the dev server from starting.

## Tests

`packages/void/test/unit/plugin-cloudflare-v2.test.ts` runs the real
plugin and Miniflare with a Docker stub, so it needs no Docker. In the
dev server, Container classes and a regular Durable Object are bound,
and unsafe bindings from the user's config are not, including one that
names another Worker's class with the same name as a local Container. In
the build, Container classes keep the unsafe form.

The test fails without the fix, without the Container class check and
without the generated-form check.

## Verification

- `vp test run`: 772 files pass, 1 skipped (15,810 tests pass, 29
skipped).
- `vp run check`: 33/33 pass.
- By hand under `vp dev` with Docker:
- `getSandbox('x')` runs `echo hi`, and the local explorer lists
`SANDBOX`.
- The acceptance route of the `kitchen-sink-sandbox` fixture passes all
12 checks.
- A renamed binding and class, a `defineDurableObject` class with a
Container, and `CLOUDFLARE_ENV` pointing at an environment with only a
`name` also work.
- Not run: a real Cloudflare deploy. The change only runs in serve, and
the test checks the binding forms in the build output.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: morinokami

packages/void/src/plugin-cloudflare-config.ts

@@ -106,6 +106,29 @@ export function toNativeCloudflareConfig(
   return { ...config, worker: config.worker };
 }
 
+/**
+ * Give Container Durable Objects a regular binding in the dev server. Their unsafe
+ * binding from `migrateBuiltWranglerConfig()` exists only for the Worker upload, and
+ * Miniflare skips unsafe bindings without a dev plugin. Match only that generated form:
+ * any other unsafe binding comes from the user's config and may name another Worker,
+ * even one with a class of the same name, so it stays as written.
+ */
+export function restoreLocalContainerBindings(worker: ParsedInputConfigWithWorker['worker']): void {
+  for (const [name, binding] of Object.entries(worker.env ?? {})) {
+    if (
+      binding.type !== 'unsafe:durable_object_namespace' ||
+      Object.keys(binding).some((key) => !['type', 'class_name'].includes(key))
+    ) {
+      continue;
+    }
+    const className = binding.class_name as string;
+    const declaration = worker.exports?.[className];
+    if (declaration && 'container' in declaration) {
+      worker.env![name] = { type: 'durable-object', worker: worker.name, exportName: className };
+    }
+  }
+}
+
 export function nativeAuxiliaryWorkers(
   workers: Array<AuxiliaryWorkerConfig> | undefined,
   root: string,

packages/void/src/plugin-cloudflare.ts

@@ -12,6 +12,7 @@ import { readGeneratedWranglerConfigFile } from './cli/generated-wrangler-config
 import {
   mergeCloudflareConfig,
   nativeAuxiliaryWorkers,
+  restoreLocalContainerBindings,
   toNativeCloudflareConfig,
   type AuxiliaryWorkerConfig,
   type WorkerConfig,
@@ -79,6 +80,8 @@ export function cloudflare(options: {
             delete declaration.container;
           }
         }
+      } else if (environment.command === 'serve') {
+        restoreLocalContainerBindings(pluginNative.worker);
       }
     },
   };

packages/void/test/unit/plugin-cloudflare-v2.test.ts

@@ -12,7 +12,7 @@ import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { getWorkerAssetsDir, readBuildOutput } from '@cloudflare/build-output-utils';
-import { createBuilder, normalizePath, preview, resolveConfig } from 'vite';
+import { createBuilder, createServer, normalizePath, preview, resolveConfig } from 'vite';
 import { afterEach, describe, expect, it, vi } from 'vite-plus/test';
 import { prepareCfBuildOutput } from '../../src/deploy.ts';
 import {
@@ -173,6 +173,117 @@ describe('Cloudflare v2 compatibility', () => {
     // Two real Vite builds take about four seconds, near the default timeout.
   }, 15_000);
 
+  // The plugin does not support local Containers on Windows.
+  it.skipIf(process.platform === 'win32')(
+    'binds Container Durable Objects in the dev server and keeps their upload form in builds',
+    async () => {
+      const root = project();
+      writeFileSync(
+        join(root, 'worker.js'),
+        `export class Box {}
+export class Sandbox {}
+export class Plain {}
+export default {
+  fetch: (_, env) =>
+    Response.json(
+      Object.fromEntries(
+        ['BOX', 'SANDBOX', 'PLAIN', 'REMOTE', 'AUTHORED'].map((name) => [
+          name,
+          typeof env[name]?.getByName,
+        ]),
+      ),
+    ),
+};
+`,
+      );
+      writeFileSync(join(root, 'Dockerfile'), 'FROM scratch\n');
+      // The dev server prepares images at startup but starts no Container until one is
+      // used, so a stub lets this test run the real plugin and Miniflare without Docker.
+      const docker = join(root, 'docker-stub');
+      writeFileSync(docker, '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+      vi.stubEnv('WRANGLER_DOCKER_BIN', docker);
+      const plugins = () =>
+        cloudflare({
+          config: () => ({
+            name: 'container-app',
+            main: 'worker.js',
+            compatibility_date: '2026-02-24',
+            durable_objects: {
+              bindings: [
+                { name: 'BOX', class_name: 'Box' },
+                { name: 'SANDBOX', class_name: 'Sandbox' },
+                { name: 'PLAIN', class_name: 'Plain' },
+              ],
+            },
+            migrations: [{ tag: 'v1', new_sqlite_classes: ['Box', 'Sandbox', 'Plain'] }],
+            containers: [
+              { name: 'box', class_name: 'Box', image: 'docker.io/example/box:1' },
+              {
+                name: 'sandbox',
+                class_name: 'Sandbox',
+                scheduling_policy: 'durable_object',
+                images: { default: { dockerfile: join(root, 'Dockerfile') } },
+              },
+            ],
+            unsafe: {
+              bindings: [
+                // Another Worker's class, named like a local Container class.
+                {
+                  name: 'REMOTE',
+                  type: 'durable_object_namespace',
+                  class_name: 'Box',
+                  script_name: 'another-worker',
+                },
+                { name: 'AUTHORED', type: 'durable_object_namespace', class_name: 'Elsewhere' },
+              ],
+            },
+          }),
+          viteEnvironment: { name: 'ssr' },
+        });
+
+      const server = await createServer({
+        root,
+        configFile: false,
+        logLevel: 'silent',
+        server: { port: 0 },
+        plugins: plugins(),
+      });
+      try {
+        await server.listen();
+        const response = await fetch(server.resolvedUrls!.local[0]!);
+        expect(await response.json()).toEqual({
+          BOX: 'function',
+          SANDBOX: 'function',
+          PLAIN: 'function',
+          REMOTE: 'undefined',
+          AUTHORED: 'undefined',
+        });
+      } finally {
+        await server.close();
+      }
+
+      const builder = await createBuilder({
+        root,
+        configFile: false,
+        logLevel: 'silent',
+        plugins: plugins(),
+      });
+      await builder.buildApp();
+      expect((await readBuildOutput(root)).workers.default.config.env).toMatchObject({
+        BOX: { type: 'unsafe:durable_object_namespace', class_name: 'Box' },
+        SANDBOX: { type: 'unsafe:durable_object_namespace', class_name: 'Sandbox' },
+        PLAIN: { type: 'durable-object', worker: 'container-app', exportName: 'Plain' },
+        REMOTE: {
+          type: 'unsafe:durable_object_namespace',
+          class_name: 'Box',
+          script_name: 'another-worker',
+        },
+        AUTHORED: { type: 'unsafe:durable_object_namespace', class_name: 'Elsewhere' },
+      });
+    },
+    15_000,
+  );
+
   it('preserves resource identities, required secrets and compatibility settings', () => {
     const root = project();
     const config = toNativeCloudflareConfig(