vite-plugin: show warning if the user has forgotten to turn on nodejs_compat (#8207)

* Add warnings to `vite dev` for when code (or a library) uses Node.js APIs without setting the `nodejs_compat` flag

* fixups

Author: petebacondarwin

.changeset/loud-worlds-ask.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/vite-plugin": patch
+---
+
+Show warning if the user has forgotten to turn on nodejs_compat

packages/vite-plugin-cloudflare/playground/node-compat/__tests__/worker-warnings/warnings.spec.ts

@@ -0,0 +1,18 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import dedent from "ts-dedent";
+import { expect, test, vi } from "vitest";
+import { serverLogs } from "../../../__test-utils__";
+
+test("should display warnings if nodejs_compat is missing", async () => {
+	await vi.waitFor(async () => {
+		expect(serverLogs.warns[0]?.replaceAll("\\", "/")).toContain(
+			dedent`
+				Unexpected Node.js imports for environment "worker". Do you need to enable the "nodejs_compat" compatibility flag?
+				Refer to https://developers.cloudflare.com/workers/runtime-apis/nodejs/ for more details.
+				 - "node:assert/strict" imported from "worker-warnings/index.ts"
+				 - "perf_hooks" imported from "worker-warnings/index.ts"
+				`
+		);
+	});
+});

packages/vite-plugin-cloudflare/playground/node-compat/package.json

@@ -33,7 +33,11 @@
 		"random:build": "vite build --app -c vite.config.worker-random.ts",
 		"random:dev": "vite dev -c vite.config.worker-random.ts",
 		"random:preview": "vite preview -c vite.config.worker-random.ts",
-		"random:test": "vitest run -c ../vitest.config.e2e.ts worker-random"
+		"random:test": "vitest run -c ../vitest.config.e2e.ts worker-random",
+		"warnings:build": "vite build --app -c vite.config.worker-warnings.ts",
+		"warnings:dev": "vite dev -c vite.config.worker-warnings.ts",
+		"warnings:preview": "vite preview -c vite.config.worker-warnings.ts",
+		"warnings:test": "vitest run -c ../vitest.config.e2e.ts worker-warnings"
 	},
 	"devDependencies": {
 		"@cloudflare/vite-plugin": "workspace:*",

packages/vite-plugin-cloudflare/playground/node-compat/tsconfig.worker.json

@@ -6,6 +6,7 @@
 		"worker-crypto",
 		"worker-postgres",
 		"worker-process",
-		"worker-random"
+		"worker-random",
+		"worker-warnings"
 	]
 }

packages/vite-plugin-cloudflare/playground/node-compat/vite.config.worker-warnings.ts

@@ -0,0 +1,15 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	build: {
+		outDir: "dist/worker-warnings",
+	},
+	plugins: [
+		cloudflare({
+			configPath: "./worker-warnings/wrangler.toml",
+			inspectorPort: false,
+			persistState: false,
+		}),
+	],
+});

packages/vite-plugin-cloudflare/playground/node-compat/worker-warnings/index.ts

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+// Check that we can actually import unenv polyfilled modules in user source.
+import "perf_hooks";
+
+export default {
+	async fetch() {
+		assert(true, "the world is broken");
+		return new Response("OK!");
+	},
+} satisfies ExportedHandler;

packages/vite-plugin-cloudflare/playground/node-compat/worker-warnings/wrangler.toml

@@ -0,0 +1,5 @@
+name = "worker"
+main = "./index.ts"
+compatibility_date = "2024-12-30"
+# Do not turn on Node.js compatibility to trigger the warnings
+# compatibility_flags = ["nodejs_compat"]

packages/vite-plugin-cloudflare/playground/package.json

@@ -14,6 +14,7 @@
 		"@cloudflare/vite-plugin": "workspace:*",
 		"@cloudflare/workers-tsconfig": "workspace:*",
 		"playwright-chromium": "catalog:default",
+		"ts-dedent": "^2.2.0",
 		"typescript": "catalog:default"
 	}
 }

packages/vite-plugin-cloudflare/src/index.ts

@@ -1,7 +1,6 @@
 import assert from "node:assert";
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
-import { builtinModules } from "node:module";
 import * as path from "node:path";
 import { createMiddleware } from "@hattip/adapter-node";
 import MagicString from "magic-string";
@@ -31,6 +30,9 @@ import {
 	injectGlobalCode,
 	isNodeCompat,
 	nodeCompatExternals,
+	NODEJS_MODULES_RE,
+	nodejsBuiltins,
+	NodeJsCompatWarnings,
 	resolveNodeJSImport,
 } from "./node-js-compat";
 import { resolvePluginConfig } from "./plugin-config";
@@ -43,7 +45,11 @@ import {
 } from "./utils";
 import { handleWebSocket } from "./websockets";
 import { getWarningForWorkersConfigs } from "./workers-configs";
-import type { PluginConfig, ResolvedPluginConfig } from "./plugin-config";
+import type {
+	PluginConfig,
+	ResolvedPluginConfig,
+	WorkerConfig,
+} from "./plugin-config";
 import type { Unstable_RawConfig } from "wrangler";
 
 export type { PluginConfig } from "./plugin-config";
@@ -66,6 +72,8 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 
 	const additionalModulePaths = new Set<string>();
 
+	const nodeJsCompatWarningsMap = new Map<WorkerConfig, NodeJsCompatWarnings>();
+
 	// This is set when the client environment is built to determine if the entry Worker should include assets
 	let hasClientBuild = false;
 
@@ -522,10 +530,7 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 							// Obviously we don't want/need the optimizer to try to process modules that are built-in;
 							// But also we want to avoid following the ones that are polyfilled since the dependency-optimizer import analyzer does not
 							// resolve these imports using our `resolveId()` hook causing the optimization step to fail.
-							exclude: [
-								...builtinModules,
-								...builtinModules.map((m) => `node:${m}`),
-							],
+							exclude: [...nodejsBuiltins],
 						},
 					};
 				}
@@ -619,7 +624,7 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 				}
 
 				const workerNames = workerConfigs.map((worker) => {
-					assert(worker.name);
+					assert(worker.name, "Expected the Worker to have a name");
 					return worker.name;
 				});
 
@@ -639,6 +644,115 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 				});
 			},
 		},
+		// Plugin to warn if Node.js APIs are being used without nodejs_compat turned on
+		{
+			name: "vite-plugin-cloudflare:nodejs-compat-warnings",
+			apply(_config, env) {
+				// Skip this whole plugin if we are in preview mode
+				return !env.isPreview;
+			},
+			configEnvironment(environmentName) {
+				const workerConfig = getWorkerConfig(environmentName);
+				if (workerConfig && !isNodeCompat(workerConfig)) {
+					return {
+						optimizeDeps: {
+							esbuildOptions: {
+								plugins: [
+									{
+										name: "vite-plugin-cloudflare:nodejs-compat-warnings-resolver",
+										setup(build) {
+											build.onResolve(
+												{ filter: NODEJS_MODULES_RE },
+												({ path, importer }) => {
+													// We have to delay getting this `nodeJsCompatWarnings` from the `nodeJsCompatWarningsMap` until we are in this function.
+													// It has not been added to the map until the `configureServer()` hook is called, which is after the `configEnvironment()` hook.
+													const nodeJsCompatWarnings =
+														nodeJsCompatWarningsMap.get(workerConfig);
+													assert(
+														nodeJsCompatWarnings,
+														`expected nodeJsCompatWarnings to be defined for Worker "${workerConfig.name}"`
+													);
+													nodeJsCompatWarnings.registerImport(path, importer);
+													// Mark this path as external to avoid messy unwanted resolve errors.
+													// It will fail at runtime but we will log warnings to the user.
+													return { path, external: true };
+												}
+											);
+											build.onEnd(() => {
+												const nodeJsCompatWarnings =
+													nodeJsCompatWarningsMap.get(workerConfig);
+												if (nodeJsCompatWarnings) {
+													nodeJsCompatWarnings.renderWarnings();
+												}
+											});
+										},
+									},
+								],
+							},
+						},
+					};
+				}
+			},
+			configureServer(viteDevServer) {
+				// Create a nodeJsCompatWarnings object for each Worker environment that has Node.js compat turned off.
+				for (const environment of Object.values(viteDevServer.environments)) {
+					const workerConfig = getWorkerConfig(environment.name);
+					if (workerConfig && !isNodeCompat(workerConfig)) {
+						nodeJsCompatWarningsMap.set(
+							workerConfig,
+							new NodeJsCompatWarnings(environment)
+						);
+					}
+				}
+			},
+			buildStart() {
+				const workerConfig = getWorkerConfig(this.environment.name);
+				if (workerConfig && !isNodeCompat(workerConfig)) {
+					nodeJsCompatWarningsMap.set(
+						workerConfig,
+						new NodeJsCompatWarnings(this.environment)
+					);
+				}
+			},
+			buildEnd() {
+				const workerConfig = getWorkerConfig(this.environment.name);
+				if (workerConfig && !isNodeCompat(workerConfig)) {
+					const nodeJsCompatWarnings =
+						nodeJsCompatWarningsMap.get(workerConfig);
+					assert(
+						nodeJsCompatWarnings,
+						`expected nodeJsCompatWarnings to be defined for Worker "${workerConfig.name}"`
+					);
+					nodeJsCompatWarnings.renderWarnings();
+				}
+			},
+			// We must ensure that the `resolveId` hook runs before the built-in ones otherwise we
+			// never see the Node.js built-in imports since they get handled by default Vite behavior.
+			enforce: "pre",
+			async resolveId(source, importer) {
+				const workerConfig = getWorkerConfig(this.environment.name);
+				if (workerConfig && !isNodeCompat(workerConfig)) {
+					const nodeJsCompatWarnings =
+						nodeJsCompatWarningsMap.get(workerConfig);
+					assert(
+						nodeJsCompatWarnings,
+						`expected nodeJsCompatWarnings to be defined for Worker "${workerConfig.name}"`
+					);
+					if (nodejsBuiltins.has(source)) {
+						nodeJsCompatWarnings.registerImport(source, importer);
+						// We don't have a natural place to trigger the rendering of the warnings
+						// So we trigger a rendering to happen soon after this round of processing.
+						nodeJsCompatWarnings.renderWarningsOnIdle();
+						// Mark this path as external to avoid messy unwanted resolve errors.
+						// It will fail at runtime but we will log warnings to the user.
+						return {
+							id: source,
+							external: true,
+						};
+					}
+				}
+			},
+		},
 	];
 
 	function getWorkerConfig(environmentName: string) {

packages/vite-plugin-cloudflare/src/node-js-compat.ts

@@ -1,9 +1,12 @@
 import assert from "node:assert";
+import { builtinModules } from "node:module";
+import path from "node:path";
 import { cloudflare } from "@cloudflare/unenv-preset";
 import MagicString from "magic-string";
 import { getNodeCompat } from "miniflare";
 import { resolvePathSync } from "mlly";
 import { defineEnv } from "unenv";
+import * as vite from "vite";
 import type { WorkerConfig } from "./plugin-config";
 
 const { env } = defineEnv({
@@ -14,12 +17,21 @@ const { env } = defineEnv({
 export const nodeCompatExternals = new Set(env.external);
 export const nodeCompatEntries = getNodeCompatEntries();
 
+/**
+ * All the Node.js modules including their `node:...` aliases.
+ */
+export const nodejsBuiltins = new Set([
+	...builtinModules,
+	...builtinModules.map((m) => `node:${m}`),
+]);
+export const NODEJS_MODULES_RE = new RegExp(
+	`^(node:)?(${builtinModules.join("|")})$`
+);
+
 /**
  * Returns true if the given combination of compat dates and flags means that we need Node.js compatibility.
  */
-export function isNodeCompat(
-	workerConfig: WorkerConfig | undefined
-): workerConfig is WorkerConfig {
+export function isNodeCompat(workerConfig: WorkerConfig | undefined) {
 	if (workerConfig === undefined) {
 		return false;
 	}
@@ -130,3 +142,43 @@ function getNodeCompatEntries() {
 
 	return entries;
 }
+
+export class NodeJsCompatWarnings {
+	private sources = new Map<string, Set<string>>();
+	private timer: NodeJS.Timeout | undefined;
+
+	constructor(private readonly environment: vite.Environment) {}
+
+	registerImport(source: string, importer = "<unknown>") {
+		const importers = this.sources.get(source) ?? new Set();
+		this.sources.set(source, importers);
+		importers.add(importer);
+	}
+
+	renderWarningsOnIdle() {
+		if (this.timer) {
+			clearTimeout(this.timer);
+		}
+		this.timer = setTimeout(() => {
+			this.renderWarnings();
+			this.timer = undefined;
+		}, 500);
+	}
+
+	renderWarnings() {
+		if (this.sources.size > 0) {
+			let message =
+				`\n\nUnexpected Node.js imports for environment "${this.environment.name}". Do you need to enable the "nodejs_compat" compatibility flag?\n` +
+				"Refer to https://developers.cloudflare.com/workers/runtime-apis/nodejs/ for more details.\n";
+			this.sources.forEach((importers, source) => {
+				importers.forEach((importer) => {
+					message += ` - "${source}" imported from "${path.relative(this.environment.config.root, importer)}"\n`;
+				});
+			});
+			this.environment.logger.warn(message, {
+				environment: this.environment.name,
+			});
+			this.sources.clear();
+		}
+	}
+}