Ensure that Node.js polyfills are pre-optimized before the first request (#8688)

* Ensure that Node.js polyfills are pre-optimized before the first request

Previously, these polyfills were only optimized on demand when Vite became aware of them.
This was either because Vite was able to find an import to a polyfill when statically analysing the import tree of the entry-point,
or when a polyfilled module was dynamically imported as part of a executing code to handle a request.

In the second case, the optimizing of the dynamically imported dependency causes a reload of the Vite server, which can break applications that are holding state in modules during the request.
This is the case of most React type frameworks, in particular React Router.

Now, we pre-optimize all the possible Node.js polyfills when the server starts before the first request is handled.

* fixup! Ensure that Node.js polyfills are pre-optimized before the first request

* add test

* simplify the  nodejs warnings plugin

* fixup! Ensure that Node.js polyfills are pre-optimized before the first request

* fixup! simplify the  nodejs warnings plugin

* add debugging to e2e tests

* fixup! Ensure that Node.js polyfills are pre-optimized before the first request

* Initialize nodeJsCompatWarnings in configResolved hook

* Fix wrangler-configs-validation e2e tests

---------

Co-authored-by: James Opstad <[email protected]>

Author: petebacondarwin

.changeset/five-camels-cheer.md

@@ -0,0 +1,14 @@
+---
+"@cloudflare/vite-plugin": patch
+---
+
+Ensure that Node.js polyfills are pre-optimized before the first request
+
+Previously, these polyfills were only optimized on demand when Vite became aware of them.
+This was either because Vite was able to find an import to a polyfill when statically analysing the import tree of the entry-point,
+or when a polyfilled module was dynamically imported as part of a executing code to handle a request.
+
+In the second case, the optimizing of the dynamically imported dependency causes a reload of the Vite server, which can break applications that are holding state in modules during the request.
+This is the case of most React type frameworks, in particular React Router.
+
+Now, we pre-optimize all the possible Node.js polyfills when the server starts before the first request is handled.

.github/workflows/e2e.yml

@@ -43,11 +43,11 @@ jobs:
       - name: Run Vite E2E tests
         run: pnpm test:e2e -F @cloudflare/vite-plugin --log-order=stream
         env:
+          NODE_DEBUG: "vite-plugin:test"
+          # The AI tests need to connect to Cloudflare
           CLOUDFLARE_API_TOKEN: ${{ secrets.TEST_CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.TEST_CLOUDFLARE_ACCOUNT_ID }}
           NODE_OPTIONS: "--max_old_space_size=8192"
-          WRANGLER_LOG_PATH: ${{ runner.temp }}/wrangler-debug-logs/
-          TEST_REPORT_PATH: ${{ runner.temp }}/test-report/index.html
           CI_OS: ${{ matrix.os }}
 
       - name: Run Wrangler E2E tests

packages/vite-plugin-cloudflare/e2e/README.md

@@ -25,17 +25,28 @@ The simplest test looks like:
 
 ```ts
 test("can serve a Worker request", async ({ expect, seed, viteDev }) => {
-	const projectPath = await seed("basic");
-	runCommand(`pnpm install`, projectPath);
+	const projectPath = await seed("basic", "pnpm");
 
 	const proc = await viteDev(projectPath);
 	const url = await waitForReady(proc);
 	expect(await fetchJson(url + "/api/")).toEqual({ name: "Cloudflare" });
 });
 ```
 
-- The `seed()` helper makes a copy of the named fixture into a temporary directory. It returns the path to the directory containing the copy (`projectPath` above). This directory will be deleted at the end of the test.
-- The `runCommand()` helper simply executes a one-shot command and resolves when it has exited. You can use this to install the dependencies of the fixture from the mock npm registry, as in the example above.
+- The `seed()` helper does the following:
+  - makes a copy of the named fixture into a temporary directory,
+  - updates the vite-plugin dependency in the package.json to match the local version
+  - runs `npm install` (or equivalent package manager command) in the temporary project
+  - returns the path to the directory containing the copy (`projectPath` above)
+  - the temporary directory will be deleted at the end of the test.
+- The `runCommand()` helper simply executes a one-shot command and resolves when it has exited. You can use this to install the dependencies of the fixture from the mock npm registry.
 - The `viteDev()` helper boots up the `vite dev` command and returns an object that can be used to monitor its output. The process will be killed at the end of the test.
 - The `waitForReady()` helper will resolve when the `vite dev` process has output its ready message, from which it will parse the url that can be fetched in the test.
 - The `fetchJson()` helper makes an Undici fetch to the url parsing the response into JSON. It will retry every 250ms for up to 10 secs to minimize flakes.
+
+## Debugging the tests
+
+You can provide the following environment variables to get access to the logs and the actual files being tested:
+
+- `NODE_DEBUG=vite-plugin:test` - this will display debugging log messages as well as the streamed output from the commands being run.
+- `CLOUDFLARE_VITE_E2E_KEEP_TEMP_DIRS=1` - this will prevent the temporary directory containing the test project from being deleted, so that you can go and play with it manually.

packages/vite-plugin-cloudflare/e2e/basic.test.ts

@@ -1,11 +1,10 @@
 import { describe } from "vitest";
-import { fetchJson, runCommand, test, waitForReady } from "./helpers.js";
+import { fetchJson, test, waitForReady } from "./helpers.js";
 
 describe("node compatibility", () => {
-	describe.each(["pnpm --no-store", "npm", "yarn"])("using %s", (pm) => {
+	describe.each(["pnpm", "npm", "yarn"])("using %s", (pm) => {
 		test("can serve a Worker request", async ({ expect, seed, viteDev }) => {
-			const projectPath = await seed("basic");
-			runCommand(`${pm} install`, projectPath);
+			const projectPath = await seed("basic", pm);
 
 			const proc = await viteDev(projectPath);
 			const url = await waitForReady(proc);
@@ -17,8 +16,7 @@ describe("node compatibility", () => {
 // This test checks that wrapped bindings which rely on additional workers with an authed connection to the CF API work
 describe("Workers AI", () => {
 	test("can serve a Worker request", async ({ expect, seed, viteDev }) => {
-		const projectPath = await seed("basic");
-		runCommand(`npm install`, projectPath);
+		const projectPath = await seed("basic", "npm");
 
 		const proc = await viteDev(projectPath);
 		const url = await waitForReady(proc);

packages/vite-plugin-cloudflare/e2e/dynamic.test.ts

@@ -0,0 +1,22 @@
+import { describe } from "vitest";
+import { fetchJson, test, waitForReady } from "./helpers.js";
+
+describe("prebundling Node.js compatibility", () => {
+	describe.each(["pnpm", "npm", "yarn"])("using %s", (pm) => {
+		test("will not cause a reload on a dynamic import of a Node.js module", async ({
+			expect,
+			seed,
+			viteDev,
+		}) => {
+			const projectPath = await seed("dynamic", pm);
+
+			const proc = await viteDev(projectPath);
+			const url = await waitForReady(proc);
+			expect(await fetchJson(url)).toEqual("OK!");
+			expect(proc.stdout).not.toContain(
+				"optimized dependencies changed. reloading"
+			);
+			expect(proc.stdout).not.toContain("[vite] program reload");
+		});
+	});
+});

packages/vite-plugin-cloudflare/e2e/fixtures/basic/package.json

@@ -1,5 +1,5 @@
 {
-	"name": "cloudflare-vite-tutorial",
+	"name": "cloudflare-vite-e2e-basic",
 	"version": "0.0.0",
 	"private": true,
 	"type": "module",

packages/vite-plugin-cloudflare/e2e/fixtures/basic/vite.config.ts

@@ -3,5 +3,5 @@ import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 
 export default defineConfig({
-	plugins: [react(), cloudflare()],
+	plugins: [react(), cloudflare({ inspectorPort: false, persistState: false })],
 });

packages/vite-plugin-cloudflare/e2e/fixtures/basic/wrangler.toml

@@ -1,4 +1,4 @@
-name = "cloudflare-vite-tutorial"
+name = "cloudflare-vite-e2e-basic"
 compatibility_date = "2024-12-30"
 compatibility_flags = [ "nodejs_compat" ]
 assets = { not_found_handling = "single-page-application", binding = "ASSETS" }

packages/vite-plugin-cloudflare/e2e/fixtures/dynamic/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "cloudflare-vite-e2e-dynamic",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build",
+		"dev": "vite",
+		"lint": "eslint .",
+		"preview": "vite preview"
+	},
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "*",
+		"@cloudflare/workers-types": "^4.20250204.0",
+		"@eslint/js": "^9.19.0",
+		"eslint": "^9.19.0",
+		"eslint-plugin-react-hooks": "^5.0.0",
+		"eslint-plugin-react-refresh": "^0.4.18",
+		"globals": "^15.14.0",
+		"typescript": "~5.7.2",
+		"typescript-eslint": "^8.22.0",
+		"vite": "^6.1.0",
+		"wrangler": "^3.108.1"
+	}
+}

packages/vite-plugin-cloudflare/e2e/fixtures/dynamic/src/dynamic.ts

@@ -0,0 +1,8 @@
+// This dynamically imported module relies upon Node.js
+// When Vite becomes aware of this file it will need to optimize the `node:asset` library
+// if it hasn't already.
+
+import assert from "node:assert/strict";
+
+assert(true, "the world is broken!");
+export const x = '"OK!"';