vite-plugin: add support for Node.js ALS compat mode (#8878)

* vite-plugin: add support for Node.js ALS compat mode

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

Co-authored-by: Dario Piotrowicz <[email protected]>

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

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

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

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

* refactor regex into `isNodeAlsModule()` shared helper

---------

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

Author: 3 people

.changeset/nasty-mice-dance.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/vite-plugin": patch
+---
+
+add support for Node.js ALS compat mode

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

@@ -0,0 +1,9 @@
+import { expect, test } from "vitest";
+import { getTextResponse, serverLogs } from "../../../__test-utils__";
+
+test("supports Node.js ALS mode", async () => {
+	const result = await getTextResponse();
+	// It won't log any node.js compat warnings
+	expect(serverLogs.warns).toEqual([]);
+	expect(result).toEqual("OK!");
+});

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

@@ -1,6 +1,7 @@
 {
 	"extends": ["@cloudflare/workers-tsconfig/worker.json"],
 	"include": [
+		"worker-als",
 		"worker-basic",
 		"worker-cross-env",
 		"worker-crypto",

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

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

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

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export default {
+	async fetch() {
+		const storage = new AsyncLocalStorage();
+		return storage.run({}, () => new Response("OK!"));
+	},
+} satisfies ExportedHandler;

packages/vite-plugin-cloudflare/playground/node-compat/worker-als/wrangler.jsonc

@@ -0,0 +1,6 @@
+{
+	"name": "worker",
+	"main": "./index.ts",
+	"compatibility_date": "2024-12-30",
+	"compatibility_flags": ["nodejs_als"],
+}

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

@@ -30,6 +30,8 @@ import {
 } from "./miniflare-options";
 import {
 	injectGlobalCode,
+	isNodeAls,
+	isNodeAlsModule,
 	isNodeCompat,
 	nodeCompatEntries,
 	nodeCompatExternals,
@@ -655,6 +657,26 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 				);
 			},
 		},
+		// Plugin that handles Node.js Async Local Storage (ALS) compatibility support for Vite Environments that are hosted in Cloudflare Workers.
+		{
+			name: "vite-plugin-cloudflare:nodejs-als",
+			apply(_config, env) {
+				// Skip this whole plugin if we are in preview mode
+				return !env.isPreview;
+			},
+			configEnvironment(name, config) {
+				if (isNodeAls(getWorkerConfig(name))) {
+					return {
+						resolve: {
+							builtins: ["async_hooks", "node:async_hooks"],
+						},
+						optimizeDeps: {
+							exclude: ["async_hooks", "node:async_hooks"],
+						},
+					};
+				}
+			},
+		},
 		// Plugin that provides an __debug path for debugging the Cloudflare Workers.
 		{
 			name: "vite-plugin-cloudflare:debug",
@@ -736,6 +758,14 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 											build.onResolve(
 												{ filter: NODEJS_MODULES_RE },
 												({ path, importer }) => {
+													if (
+														isNodeAls(workerConfig) &&
+														isNodeAlsModule(path)
+													) {
+														// Skip if this is just async_hooks and Node.js ALS support is on.
+														return;
+													}
+
 													const nodeJsCompatWarnings =
 														nodeJsCompatWarningsMap.get(workerConfig);
 													nodeJsCompatWarnings?.registerImport(path, importer);
@@ -770,6 +800,11 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 				const workerConfig = getWorkerConfig(this.environment.name);
 
 				if (workerConfig && !isNodeCompat(workerConfig)) {
+					if (isNodeAls(workerConfig) && isNodeAlsModule(source)) {
+						// Skip if this is just async_hooks and Node.js ALS support is on.
+						return;
+					}
+
 					const nodeJsCompatWarnings =
 						nodeJsCompatWarningsMap.get(workerConfig);
 

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

@@ -50,6 +50,23 @@ export function isNodeCompat(workerConfig: WorkerConfig | undefined) {
 	return false;
 }
 
+/**
+ * Returns true if Node.js async local storage (ALS) is enabled (and not full Node.js compatibility mode).
+ */
+export function isNodeAls(workerConfig: WorkerConfig | undefined) {
+	return (
+		workerConfig !== undefined &&
+		getNodeCompat(
+			workerConfig.compatibility_date,
+			workerConfig.compatibility_flags ?? []
+		).mode === "als"
+	);
+}
+
+export function isNodeAlsModule(path: string) {
+	return /^(node:)?async_hooks$/.test(path);
+}
+
 /**
  * Gets the necessary global polyfills to inject into the entry-point of the user's code.
  */

packages/vite-plugin-cloudflare/src/worker-environments-validation.ts

@@ -1,6 +1,11 @@
 import assert from "node:assert";
 import { cloudflareBuiltInModules } from "./cloudflare-environment";
-import { isNodeCompat, NODEJS_MODULES_RE } from "./node-js-compat";
+import {
+	isNodeAls,
+	isNodeAlsModule,
+	isNodeCompat,
+	NODEJS_MODULES_RE,
+} from "./node-js-compat";
 import type { WorkerPluginConfig } from "./plugin-config";
 import type * as vite from "vite";
 
@@ -41,11 +46,19 @@ export function validateWorkerEnvironmentsResolvedConfigs(
 				return false;
 			}
 
+			if (
+				isNodeAlsModule(entry) &&
+				isNodeAls(resolvedPluginConfig.workers[envName])
+			) {
+				// `node:async_hooks` is allowed when nodejs_als compat is enabled
+				return false;
+			}
+
 			if (
 				NODEJS_MODULES_RE.test(entry) &&
 				isNodeCompat(resolvedPluginConfig.workers[envName])
 			) {
-				// node builtin modules are allowed when but nodejs compat is enabled
+				// node builtin modules are allowed when nodejs compat is enabled
 				return false;
 			}