fix: resolve island CSS paths and deploy compat flag mismatch (#71)

## Control flow analysis

### Build time (works)

1. User runs `void deploy` from `playground/react-pages/`
2. The CLI shells out to `vite build`, which invokes
`@cloudflare/vite-plugin`
3. The plugin builds two environments: **client** (browser JS) and
**ssr** (worker bundle)
4. During the SSR build, the virtual renderer module is generated:
   ```js
   import React from "react";
   import { renderToString } from "react-dom/server";
import { SharedContext, ErrorsContext, RouterContext } from
"@void/react";
   ```
5. `@void/react` is a pre-built npm package whose dist imports `{
createContext, useContext } from "react"`
6. Rolldown bundles everything into a module graph under `dist/ssr/` --
`index.js` + `assets/*.js` chunks
7. React ends up in a single CJS-wrapped chunk (`react-BVLPaBiV.js`)
shared by all consumers. **No dual React.**
8. `@cloudflare/vite-plugin` writes `dist/ssr/wrangler.json` with
`compatibility_flags: ["nodejs_als"]` and `compatibility_date:
"2026-03-29"`

### Deploy packaging (the first bug)

9. The CLI calls `readWranglerCompat(root, config)` to get compat
settings for the deploy manifest
10. It looks for `wrangler.json` at the **project root**
(`playground/react-pages/`) -- **does not exist**
11. It looks for `worker.compatibility_flags` in `void.json` -- **not
set**
12. Falls back to hardcoded defaults: `compatibility_date:
"2026-02-12"`, `compatibilityFlags: undefined`
13. The build output's `dist/ssr/wrangler.json` (which has the correct
settings) is **never read**
14. The CLI packages all worker files from `dist/ssr/` into a FormData
with the manifest
15. The manifest has `compatibilityFlags: undefined`

### Server-side deploy (the second bug)

16. The platform API (`packages/api/src/routes/deploy.ts`) receives the
FormData
17. It builds WfP upload metadata:
    ```js
compatibility_flags: manifest.compatibilityFlags ?? ["nodejs_compat"]
    ```
18. Since `manifest.compatibilityFlags` is `undefined`, the fallback
`["nodejs_compat"]` kicks in
19. The worker is uploaded to Workers for Platforms with:
- `compatibility_flags: ["nodejs_compat"]` (wrong -- should be
`["nodejs_als"]`)
- `compatibility_date: "2026-02-12"` (wrong -- should be `"2026-03-29"`)

### Runtime (the crash)

20. A request hits `https://void-test-it.void.app/`
21. The dispatch worker (`packages/dispatch`) routes it to the user's
WfP worker
22. The worker's `index.js` entry handles the request via Hono
23. The route handler calls `handlePageGet(...)` which calls
`renderPage(pageObj, assetTags)`
24. The virtual renderer builds the React element tree:
    ```js
element = React.createElement(SharedContext.Provider, { value: shared },
      React.createElement(ErrorsContext.Provider, { value: errors },
        React.createElement(RouterContext.Provider, { value: null },
          React.createElement(Layout, null,
            React.createElement(HomePage, props)))))
    ```
25. It calls `renderToString(element)` -- this enters React's server
renderer
26. React's server renderer sets `ReactSharedInternals.H =
serverDispatcher` and begins rendering
27. The `Layout` component runs, calls `useShared()` ->
`useContext(SharedContext)`
28. `useContext` internally does
`ReactSharedInternals.H.useContext(context)`
29. **Under `nodejs_compat` at compat date `2026-02-12` on WfP**,
`ReactSharedInternals.H` is `null` at this point -- the dispatcher set
by `renderToString` is not visible to the `useContext` call
30. **`null.useContext`** -> `TypeError: Cannot read properties of null
(reading 'useContext')`
31. The worker returns 500

### Why it works locally

- **`vite dev`**: No bundling. `@void/react` is excluded from dep
optimization (`optimizeDeps.exclude`), so all code shares the same live
React module. `nodejs_als` is used by the Cloudflare plugin's dev
server.
- **`wrangler dev` on build output**: Reads `dist/ssr/wrangler.json`
directly, which has the correct `nodejs_als` flag and `2026-03-29` date.
The local workerd runtime evaluates modules correctly under these
settings.

### The fix

The deploy pipeline now reads the build output's `wrangler.json` as a
fallback source for compat settings (priority: `void.json` > project
`wrangler.json` > build output `wrangler.json` > hardcoded default).
This ensures the deployed worker runs with the same flags the build was
designed for.

Also fixes a separate build failure where island CSS imports with
relative paths (e.g. `import "./global.css"` in a layout) were copied
verbatim into the virtual islands-client entry module, where they could
not resolve. Now rewrites them to absolute paths.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Brooooooklyn

packages/react/src/plugin-islands.ts

@@ -11,6 +11,7 @@ import {
   rebuildIslandCssMap,
   computePagesNeedingClientJS,
   configureIslandCssServer,
+  rewriteCssImportForVirtualModule,
   ISLANDS_RENDERER_ID,
   ISLANDS_CLIENT_ENTRY_ID,
 } from "void/pages-islands-plugin";
@@ -375,7 +376,7 @@ function generateIslandClientEntry(
       cssImportRe.lastIndex = 0;
       let match;
       while ((match = cssImportRe.exec(content)) !== null) {
-        lines.push(match[0].trim() + ";");
+        lines.push(rewriteCssImportForVirtualModule(match[0], match[1], file));
       }
     }
   }

packages/solid/src/plugin-islands.ts

@@ -7,6 +7,7 @@ import { generateComponentManifest } from "./pages-manifest";
 import {
   resolveSpecifier,
   needsIslandClientBundle,
+  rewriteCssImportForVirtualModule,
   fileHasCssImports,
   extractCssImports,
   rebuildIslandCssMap as rebuildIslandCssMapShared,
@@ -397,7 +398,7 @@ function generateIslandClientEntry(
       cssImportRe.lastIndex = 0;
       let match;
       while ((match = cssImportRe.exec(content)) !== null) {
-        lines.push(match[0].trim() + ";");
+        lines.push(rewriteCssImportForVirtualModule(match[0], match[1], file));
       }
     }
   }

packages/svelte/src/plugin-islands.ts

@@ -6,6 +6,7 @@ import type { PageScanResult } from "void/pages";
 import {
   resolveSpecifier,
   needsIslandClientBundle,
+  rewriteCssImportForVirtualModule,
   fileHasCssImports,
   extractCssImports,
   rebuildIslandCssMap as rebuildIslandCssMapShared,
@@ -441,7 +442,7 @@ function generateIslandClientEntry(
         let cssMatch;
         cssImportRe.lastIndex = 0;
         while ((cssMatch = cssImportRe.exec(scriptContent)) !== null) {
-          lines.push(cssMatch[0].trim() + ";");
+          lines.push(rewriteCssImportForVirtualModule(cssMatch[0], cssMatch[1], file));
         }
       }
     }

packages/void/src/cli/deploy.ts

@@ -515,8 +515,11 @@ async function runFrameworkDeploy(
     log.info("Wrapper generated");
   }
 
-  // 8. Read wrangler compat settings (void.json > wrangler.jsonc > default)
-  const wranglerCompat = readWranglerCompat(root, voidConfig);
+  // 8. Read wrangler compat settings (void.json > wrangler.jsonc > build output > default)
+  // Use the original workerDir (not actualWorkerDir) because bundleEntry() may
+  // reassign actualWorkerDir to a temporary output — the plugin-generated
+  // wrangler.json with correct compat settings lives in the original build output.
+  const wranglerCompat = readWranglerCompat(root, voidConfig, workerDir);
 
   // 9. Resolve revalidate + prerender from void.json
   const revalidate = voidConfig.routing?.revalidate;
@@ -837,8 +840,8 @@ async function runFullDeploy(
             persistDir: join(root, ".void"),
           });
 
-  // 8. Read wrangler compat settings (void.json > wrangler.jsonc > default)
-  const wranglerCompat = readWranglerCompat(root, deployConfig);
+  // 8. Read wrangler compat settings (void.json > wrangler.jsonc > build output > default)
+  const wranglerCompat = readWranglerCompat(root, deployConfig, join(distDir, workerDirName));
 
   // 9. Load .env vars for production (excludes .local files)
   const envVars = loadDeployEnv(root);

packages/void/src/cli/wrangler.ts

@@ -19,12 +19,20 @@ export interface WranglerCompat {
 
 /**
  * Read compatibility settings from `wrangler.jsonc`/`wrangler.json` and
- * `void.json`, with priority: void.json > wrangler.jsonc > built-in default.
+ * `void.json`, with priority: void.json > wrangler.jsonc > build output > built-in default.
  *
  * Always returns a `compatibilityDate` (falls back to `DEFAULT_COMPAT_DATE`).
+ *
+ * @param buildOutputDir - Optional path to the build output directory (e.g.
+ *   `dist/ssr`) which may contain a plugin-generated `wrangler.json` with the
+ *   correct compat settings for the built worker.
  */
-export function readWranglerCompat(root: string, config?: VoidConfig): WranglerCompat {
-  // 1. Read wrangler.jsonc / wrangler.json
+export function readWranglerCompat(
+  root: string,
+  config?: VoidConfig,
+  buildOutputDir?: string,
+): WranglerCompat {
+  // 1. Read wrangler.jsonc / wrangler.json from project root
   let raw: string | undefined;
   for (const name of ["wrangler.jsonc", "wrangler.json"]) {
     try {
@@ -55,16 +63,37 @@ export function readWranglerCompat(root: string, config?: VoidConfig): WranglerC
     }
   }
 
+  // 1b. Read build output wrangler.json as fallback (generated by @cloudflare/vite-plugin)
+  let buildDate: string | undefined;
+  let buildFlags: string[] | undefined;
+  if (buildOutputDir) {
+    try {
+      const buildRaw = readFileSync(join(buildOutputDir, "wrangler.json"), "utf-8");
+      const buildParsed = JSON.parse(buildRaw);
+      if (typeof buildParsed.compatibility_date === "string") {
+        buildDate = buildParsed.compatibility_date;
+      }
+      if (
+        Array.isArray(buildParsed.compatibility_flags) &&
+        buildParsed.compatibility_flags.every((f: unknown) => typeof f === "string")
+      ) {
+        buildFlags = buildParsed.compatibility_flags;
+      }
+    } catch {
+      // no build output wrangler.json
+    }
+  }
+
   // 2. Override with void.json worker fields (higher priority)
   const voidDate = config?.worker?.compatibility_date;
   const voidFlags = config?.worker?.compatibility_flags;
 
-  // 3. Merge: void.json > wrangler.jsonc > default
+  // 3. Merge: void.json > project wrangler.jsonc > build output > default
   const result: WranglerCompat = {
-    compatibilityDate: voidDate ?? wranglerDate ?? DEFAULT_COMPAT_DATE,
+    compatibilityDate: voidDate ?? wranglerDate ?? buildDate ?? DEFAULT_COMPAT_DATE,
   };
 
-  const flags = voidFlags ?? wranglerFlags;
+  const flags = voidFlags ?? wranglerFlags ?? buildFlags;
   if (flags && flags.length > 0) {
     result.compatibilityFlags = flags;
   }

packages/void/src/pages/islands-plugin.ts

@@ -1,6 +1,6 @@
 import { normalizePath, type ViteDevServer } from "vite";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { resolveEffectiveLayoutChain } from "./scan";
 import type { PageScanResult } from "./types";
 
@@ -75,6 +75,22 @@ export function fileHasCssImports(filePath: string): boolean {
   }
 }
 
+/**
+ * Rewrite a matched CSS import line so relative specifiers resolve from the
+ * virtual module. Absolute and bare specifiers are kept as-is.
+ */
+export function rewriteCssImportForVirtualModule(
+  matchedLine: string,
+  specifier: string,
+  sourceFilePath: string,
+): string {
+  if (specifier.startsWith(".")) {
+    const absPath = normalizePath(resolve(dirname(sourceFilePath), specifier));
+    return `import ${JSON.stringify(absPath)};`;
+  }
+  return matchedLine.trim() + ";";
+}
+
 /** Extract CSS import statements from a file and return them as @import rules. */
 export function extractCssImports(filePath: string): string {
   const code = readFileSync(filePath, "utf-8");

packages/void/test/unit/island-css-rewrite.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { rewriteCssImportForVirtualModule } from "../../src/pages/islands-plugin";
+
+describe("rewriteCssImportForVirtualModule", () => {
+  it("rewrites relative CSS import to absolute path", () => {
+    const result = rewriteCssImportForVirtualModule(
+      'import "./global.css"',
+      "./global.css",
+      "/project/pages/layout.tsx",
+    );
+    expect(result).toBe('import "/project/pages/global.css";');
+  });
+
+  it("rewrites parent-relative CSS import to absolute path", () => {
+    const result = rewriteCssImportForVirtualModule(
+      'import "../styles/theme.css"',
+      "../styles/theme.css",
+      "/project/pages/blog/index.tsx",
+    );
+    expect(result).toBe('import "/project/pages/styles/theme.css";');
+  });
+
+  it("preserves bare specifiers (package imports)", () => {
+    const result = rewriteCssImportForVirtualModule(
+      'import "@void/md/theme.css"',
+      "@void/md/theme.css",
+      "/project/pages/layout.tsx",
+    );
+    expect(result).toBe('import "@void/md/theme.css";');
+  });
+
+  it("preserves absolute specifiers", () => {
+    const result = rewriteCssImportForVirtualModule(
+      'import "/absolute/path/style.css"',
+      "/absolute/path/style.css",
+      "/project/pages/layout.tsx",
+    );
+    expect(result).toBe('import "/absolute/path/style.css";');
+  });
+
+  it("trims whitespace from non-relative imports", () => {
+    const result = rewriteCssImportForVirtualModule(
+      '  import "some-lib/styles.css"  ',
+      "some-lib/styles.css",
+      "/project/pages/layout.tsx",
+    );
+    expect(result).toBe('import "some-lib/styles.css";');
+  });
+
+  it("normalizes backslashes to forward slashes", () => {
+    // normalizePath ensures Windows-style paths become valid import specifiers
+    const result = rewriteCssImportForVirtualModule(
+      'import "./card.css"',
+      "./card.css",
+      "/project/pages/components/deep/Card.tsx",
+    );
+    // Should always use forward slashes regardless of OS
+    expect(result).not.toContain("\\");
+    expect(result).toBe('import "/project/pages/components/deep/card.css";');
+  });
+});

packages/void/test/unit/wrangler.test.ts

@@ -134,6 +134,102 @@ describe("readWranglerCompat", () => {
     setup("wrangler.json", '{ "compatibility_date": "2026-02" }');
     expect(() => readWranglerCompat(tmpDir)).toThrow("YYYY-MM-DD format");
   });
+
+  it("falls back to build output wrangler.json when no project config exists", () => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    mkdirSync(tmpDir, { recursive: true });
+    const buildDir = join(tmpDir, "dist", "ssr");
+    mkdirSync(buildDir, { recursive: true });
+    writeFileSync(
+      join(buildDir, "wrangler.json"),
+      JSON.stringify({
+        compatibility_date: "2026-03-29",
+        compatibility_flags: ["nodejs_als"],
+      }),
+    );
+    expect(readWranglerCompat(tmpDir, undefined, buildDir)).toEqual({
+      compatibilityDate: "2026-03-29",
+      compatibilityFlags: ["nodejs_als"],
+    });
+  });
+
+  it("project wrangler.json takes priority over build output", () => {
+    setup(
+      "wrangler.json",
+      JSON.stringify({
+        compatibility_date: "2026-04-01",
+        compatibility_flags: ["nodejs_compat"],
+      }),
+    );
+    const buildDir = join(tmpDir, "dist", "ssr");
+    mkdirSync(buildDir, { recursive: true });
+    writeFileSync(
+      join(buildDir, "wrangler.json"),
+      JSON.stringify({
+        compatibility_date: "2026-03-29",
+        compatibility_flags: ["nodejs_als"],
+      }),
+    );
+    expect(readWranglerCompat(tmpDir, undefined, buildDir)).toEqual({
+      compatibilityDate: "2026-04-01",
+      compatibilityFlags: ["nodejs_compat"],
+    });
+  });
+
+  it("void.json takes priority over both project and build output", () => {
+    setup(
+      "wrangler.json",
+      JSON.stringify({ compatibility_date: "2026-01-01", compatibility_flags: ["flag_a"] }),
+    );
+    const buildDir = join(tmpDir, "dist", "ssr");
+    mkdirSync(buildDir, { recursive: true });
+    writeFileSync(
+      join(buildDir, "wrangler.json"),
+      JSON.stringify({ compatibility_date: "2026-02-01", compatibility_flags: ["flag_b"] }),
+    );
+    const config: VoidConfig = {
+      worker: { compatibility_date: "2026-06-01", compatibility_flags: ["flag_c"] },
+    };
+    expect(readWranglerCompat(tmpDir, config, buildDir)).toEqual({
+      compatibilityDate: "2026-06-01",
+      compatibilityFlags: ["flag_c"],
+    });
+  });
+
+  it("build output date used when project has no date but build output does", () => {
+    setup("wrangler.json", '{ "name": "test" }');
+    const buildDir = join(tmpDir, "dist", "ssr");
+    mkdirSync(buildDir, { recursive: true });
+    writeFileSync(
+      join(buildDir, "wrangler.json"),
+      JSON.stringify({ compatibility_date: "2026-03-29" }),
+    );
+    expect(readWranglerCompat(tmpDir, undefined, buildDir)).toEqual({
+      compatibilityDate: "2026-03-29",
+    });
+  });
+
+  it("build output flags used when project has no flags but build output does", () => {
+    setup("wrangler.json", '{ "compatibility_date": "2026-04-01" }');
+    const buildDir = join(tmpDir, "dist", "ssr");
+    mkdirSync(buildDir, { recursive: true });
+    writeFileSync(
+      join(buildDir, "wrangler.json"),
+      JSON.stringify({ compatibility_flags: ["nodejs_als"] }),
+    );
+    expect(readWranglerCompat(tmpDir, undefined, buildDir)).toEqual({
+      compatibilityDate: "2026-04-01",
+      compatibilityFlags: ["nodejs_als"],
+    });
+  });
+
+  it("ignores missing build output directory gracefully", () => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    mkdirSync(tmpDir, { recursive: true });
+    expect(readWranglerCompat(tmpDir, undefined, join(tmpDir, "nonexistent"))).toEqual({
+      compatibilityDate: DEFAULT_COMPAT_DATE,
+    });
+  });
 });
 
 const noBindings: InferredBindings = {

packages/vue/src/plugin-islands.ts

@@ -6,6 +6,7 @@ import type { PageScanResult } from "void/pages";
 import {
   resolveSpecifier,
   needsIslandClientBundle,
+  rewriteCssImportForVirtualModule,
   rebuildIslandCssMap as rebuildIslandCssMapShared,
   computePagesNeedingClientJS as computePagesNeedingClientJSShared,
   configureIslandCssServer,
@@ -442,7 +443,7 @@ function generateIslandClientEntry(
       // Extract JS-style CSS imports (e.g. import "@void/md/theme.css")
       cssImportRe.lastIndex = 0;
       while ((match = cssImportRe.exec(content)) !== null) {
-        lines.push(match[0].trim() + ";");
+        lines.push(rewriteCssImportForVirtualModule(match[0], match[1], file));
       }
     }
   }