Support serving HTML in experimental.bundledDev (#14883)

jamesopstad · web-flow · commit 76e6014ccc15 · 2026-07-28T09:42:15.000+01:00
diff --git a/.changeset/vite-plugin-bundled-dev-html.md b/.changeset/vite-plugin-bundled-dev-html.md
@@ -0,0 +1,7 @@
+---
+"@cloudflare/vite-plugin": minor
+---
+
+Serve the bundled client HTML in dev when Vite's `experimental.bundledDev` is enabled
+
+Note that this feature is experimental and subject to change.
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/base-tests.ts b/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/base-tests.ts
@@ -1,18 +1,29 @@
 import { test, vi } from "vitest";
 import { page, WAIT_FOR_OPTIONS } from "../../__test-utils__";
 
-test("returns the correct home page", async ({ expect }) => {
-	const content = await page.textContent("h1");
-	expect(content).toBe("Vite + React");
-});
+export function runBaseTests() {
+	test("returns the correct home page", async ({ expect }) => {
+		const content = await page.textContent("h1");
+		expect(content).toBe("Vite + React");
+	});
 
-test("returns the response from the API", async ({ expect }) => {
-	const button = page.getByRole("button", { name: "get-name" });
-	const contentBefore = await button.innerText();
-	expect(contentBefore).toBe("Name from API is: unknown");
-	await button.click();
-	await vi.waitFor(async () => {
-		const contentAfter = await button.innerText();
-		expect(contentAfter).toBe("Name from API is: Cloudflare");
-	}, WAIT_FOR_OPTIONS);
-});
+	test("returns the response from the API", async ({ expect }) => {
+		const button = page.getByRole("button", { name: "get-name" });
+		const contentBefore = await button.innerText();
+		expect(contentBefore).toBe("Name from API is: unknown");
+		// The outer `waitFor` re-clicks in case the initial-build `full-reload`
+		// under `experimental.bundledDev` resets the SPA state and discards an
+		// earlier click. The inner `waitFor` then waits for the API response after
+		// each click so latency is tolerated.
+		await vi.waitFor(async () => {
+			await button.click();
+			await vi.waitFor(
+				async () => {
+					const contentAfter = await button.innerText();
+					expect(contentAfter).toBe("Name from API is: Cloudflare");
+				},
+				{ timeout: 1_000, interval: 100 }
+			);
+		}, WAIT_FOR_OPTIONS);
+	});
+}
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/child-compiler/spa-with-api.spec.ts b/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/child-compiler/spa-with-api.spec.ts
@@ -1 +1,3 @@
-import "../base-tests";
+import { runBaseTests } from "../base-tests";
+
+runBaseTests();
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/client-bundled-dev/spa-with-api.spec.ts b/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/client-bundled-dev/spa-with-api.spec.ts
@@ -0,0 +1,12 @@
+import { describe } from "vitest";
+import { satisfiesMinimumViteVersion } from "../../../__test-utils__";
+import { runBaseTests } from "../base-tests";
+
+// `experimental.bundledDev` is a Vite 8+ feature, so this variant is only
+// exercised there. On older Vite versions the tests are skipped.
+describe.runIf(satisfiesMinimumViteVersion("8.0.0"))(
+	"client-bundled-dev",
+	() => {
+		runBaseTests();
+	}
+);
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/custom-output-directories/spa-with-api.spec.ts b/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/custom-output-directories/spa-with-api.spec.ts
@@ -2,7 +2,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { describe, test, vi } from "vitest";
 import { isBuild, rootDir, WAIT_FOR_OPTIONS } from "../../../__test-utils__";
-import "../base-tests";
+import { runBaseTests } from "../base-tests";
+
+runBaseTests();
 
 describe.runIf(isBuild)("output directories", () => {
 	test("creates the correct output directories", async ({ expect }) => {
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/https/spa-with-api.spec.ts b/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/https/spa-with-api.spec.ts
@@ -1 +1,3 @@
-import "../base-tests";
+import { runBaseTests } from "../base-tests";
+
+runBaseTests();
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/run-worker-first/spa-with-api.spec.ts b/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/run-worker-first/spa-with-api.spec.ts
@@ -6,7 +6,9 @@ import {
 	isBuild,
 	viteTestUrl,
 } from "../../../__test-utils__";
-import "../base-tests";
+import { runBaseTests } from "../base-tests";
+
+runBaseTests();
 
 test("returns the home page via the Worker", async ({ expect }) => {
 	const response = await getResponse();
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/spa-with-api.spec.ts b/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/spa-with-api.spec.ts
@@ -9,7 +9,9 @@ import {
 	rootDir,
 	viteTestUrl,
 } from "../../__test-utils__";
-import "./base-tests";
+import { runBaseTests } from "./base-tests";
+
+runBaseTests();
 
 test("returns the home page directly without invoking the Worker", async ({
 	expect,
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/static-routing/spa-with-api.spec.ts b/packages/vite-plugin-cloudflare/playground/spa-with-api/__tests__/static-routing/spa-with-api.spec.ts
@@ -6,7 +6,9 @@ import {
 	isBuild,
 	viteTestUrl,
 } from "../../../__test-utils__";
-import "../base-tests";
+import { runBaseTests } from "../base-tests";
+
+runBaseTests();
 
 test("returns the home page directly without invoking the Worker", async ({
 	expect,
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/package.json b/packages/vite-plugin-cloudflare/playground/spa-with-api/package.json
@@ -3,13 +3,15 @@
 	"private": true,
 	"type": "module",
 	"scripts": {
+		"build:client-bundled-dev": "vite build -c ./vite.config.client-bundled-dev.ts",
 		"build:custom-output-directories": "vite build -c ./vite.config.custom-output-directories.ts",
 		"build:default": "vite build",
 		"build:https": "vite build -c ./vite.config.https.ts",
 		"build:run-worker-first": "vite build -c ./vite.config.run-worker-first.ts",
 		"build:static-routing": "vite build -c ./vite.config.static-routing.ts",
 		"check:type": "tsc --build",
 		"dev": "vite dev",
+		"dev:client-bundled-dev": "vite dev -c ./vite.config.client-bundled-dev.ts",
 		"dev:https": "vite dev -c ./vite.config.https.ts",
 		"dev:run-worker-first": "vite dev -c ./vite.config.run-worker-first.ts",
 		"dev:static-routing": "vite dev -c ./vite.config.static-routing.ts",
diff --git a/packages/vite-plugin-cloudflare/playground/spa-with-api/vite.config.client-bundled-dev.ts b/packages/vite-plugin-cloudflare/playground/spa-with-api/vite.config.client-bundled-dev.ts
@@ -0,0 +1,19 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+import { satisfiesMinimumViteVersion } from "../__test-utils__/vite-version";
+
+export default defineConfig(
+	// `experimental.bundledDev` is a Vite 8+ feature so these tests are skipped
+	// on older Vite versions. We return an empty Vite config so that the dev
+	// server can still start quickly.
+	!satisfiesMinimumViteVersion("8.0.0")
+		? {}
+		: {
+				experimental: { bundledDev: true },
+				plugins: [
+					react(),
+					cloudflare({ inspectorPort: false, persistState: false }),
+				],
+			}
+);
diff --git a/packages/vite-plugin-cloudflare/src/__tests__/bundled-dev-dispose.spec.ts b/packages/vite-plugin-cloudflare/src/__tests__/bundled-dev-dispose.spec.ts
diff --git a/packages/vite-plugin-cloudflare/src/miniflare-options.ts b/packages/vite-plugin-cloudflare/src/miniflare-options.ts
@@ -2,6 +2,7 @@ import assert from "node:assert";
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
+import * as timers from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { format } from "node:util";
 import {
@@ -232,25 +233,76 @@ export async function getDevMiniflareOptions(
 				},
 				__VITE_FETCH_HTML__: async (request) => {
 					const { pathname } = new URL(request.url);
-					const { root, publicDir } = resolvedViteConfig;
-					const isInPublicDir = pathname.startsWith(PUBLIC_DIR_PREFIX);
-					const resolvedPath = isInPublicDir
-						? path.join(publicDir, pathname.slice(PUBLIC_DIR_PREFIX.length))
-						: path.join(root, pathname);
 
 					try {
-						let html = await fsp.readFile(resolvedPath, "utf-8");
+						const { root, publicDir } = resolvedViteConfig;
+						const isInPublicDir = pathname.startsWith(PUBLIC_DIR_PREFIX);
+
+						// HTML files in the public directory are served as-is (no
+						// transform) from disk in both bundled and non-bundled dev.
+						if (isInPublicDir) {
+							const resolvedPath = path.join(
+								publicDir,
+								pathname.slice(PUBLIC_DIR_PREFIX.length)
+							);
+							const html = await fsp.readFile(resolvedPath, "utf-8");
+
+							return new MiniflareResponse(html, {
+								headers: { "Content-Type": "text/html" },
+							});
+						}
+
+						const bundledDev = viteDevServer.environments.client.bundledDev;
+
+						if (bundledDev) {
+							// When the client environment runs in bundled dev mode
+							// (`experimental.bundledDev`), the transformed HTML lives in
+							// Vite's in-memory files rather than on disk. Serving it here
+							// ensures the returned HTML references the bundled client
+							// chunks (which Vite serves from `memoryFiles`) instead of the
+							// raw source entry.
+							//
+							// Unlike Vite's `indexHtmlMiddleware`, which serves a fallback
+							// loading page and relies on an HMR reload, we intentionally
+							// block briefly and serve the real HTML.
+							await bundledDev.triggerBundleRegenerationIfStale();
+
+							const key = pathname.slice(1);
+							let file = bundledDev.memoryFiles.get(key);
+							const deadline = Date.now() + 10_000;
+							while (!file && Date.now() < deadline) {
+								await timers.setTimeout(10);
+								file = bundledDev.memoryFiles.get(key);
+							}
 
-						// HTML files in the public directory should not be transformed
-						if (!isInPublicDir) {
-							html = await viteDevServer.transformIndexHtml(resolvedPath, html);
+							if (!file) {
+								throw new Error(
+									`No bundled file for "${pathname}" after waiting for bundle regeneration.`
+								);
+							}
+
+							const html =
+								typeof file.source === "string"
+									? file.source
+									: Buffer.from(file.source);
+
+							return new MiniflareResponse(html, {
+								headers: { "Content-Type": "text/html" },
+							});
 						}
 
+						// Non-bundled dev: read root HTML from disk and transform via Vite.
+						const resolvedPath = path.join(root, pathname);
+						let html = await fsp.readFile(resolvedPath, "utf-8");
+						html = await viteDevServer.transformIndexHtml(resolvedPath, html);
+
 						return new MiniflareResponse(html, {
 							headers: { "Content-Type": "text/html" },
 						});
-					} catch {
-						throw new Error(`Unexpected error. Failed to load "${pathname}".`);
+					} catch (error) {
+						throw new Error(`Unexpected error. Failed to load "${pathname}".`, {
+							cause: error,
+						});
 					}
 				},
 			},
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
