Mark node:* imports as external when using the nodejs_compat comp…

…atibility flag

.changeset/rare-houses-rest.md

@@ -0,0 +1,7 @@
+---
+"wrangler": patch
+---
+
+feat: Add support for the `nodejs_compat` Compatibility Flag when bundling a Worker with Wrangler
+
+This new Compatibility Flag is incompatible with the legacy `--node-compat` CLI argument and `node_compat` configuration option. If you want to use the new runtime Node.js compatibility features, please remove the `--node-compat` argument from your CLI command or your config file.

packages/wrangler/src/__tests__/dev.test.tsx

@@ -1566,6 +1566,21 @@ describe("wrangler dev", () => {
 		`);
 		});
 	});
+
+	describe("`nodejs_compat` compatibility flag", () => {
+		it("should conflict with the --node-compat option", async () => {
+			writeWranglerToml();
+			fs.writeFileSync("index.js", `export default {};`);
+
+			await expect(
+				runWrangler(
+					"dev index.js --compatibility-flag=nodejs_compat --node-compat"
+				)
+			).rejects.toThrowErrorMatchingInlineSnapshot(
+				`"The \`nodejs_compat\` compatibility flag cannot be used in conjunction with the legacy \`--node-compat\` flag. If you want to use the Workers runtime Node.js compatibility features, please remove the \`--node-compat\` argument from your CLI command or \`node_compat = true\` from your config file."`
+			);
+		});
+	});
 });
 
 function mockGetZones(domain: string, zones: { id: string }[] = []) {

packages/wrangler/src/__tests__/pages/functions-build.test.ts

@@ -399,4 +399,55 @@ export default {
 
 		expect(std.err).toMatchInlineSnapshot(`""`);
 	});
+
+	it("should leave Node.js imports when the `nodejs_compat` compatibility flag is set", async () => {
+		mkdirSync("functions");
+		writeFileSync(
+			"functions/hello.js",
+			`
+		import { AsyncLocalStorage } from 'node:async_hooks';
+
+    export async function onRequest() {
+			console.log(AsyncLocalStorage);
+      return new Response("Hello from Pages Functions");
+    }
+    `
+		);
+
+		await runWrangler(
+			`pages functions build --outfile=public/_worker.js --compatibility-flag=nodejs_compat`
+		);
+
+		expect(existsSync("public/_worker.js")).toBe(true);
+		expect(std.out).toMatchInlineSnapshot(`
+		"🚧 'wrangler pages <command>' is a beta command. Please report any issues to https://github.com/cloudflare/workers-sdk/issues/new/choose
+		✨ Compiled Worker successfully"
+	`);
+
+		expect(readFileSync("public/_worker.js", "utf-8")).toContain(
+			`import { AsyncLocalStorage } from "node:async_hooks";`
+		);
+	});
+
+	it("should error at Node.js imports when the `nodejs_compat` compatibility flag is not set", async () => {
+		mkdirSync("functions");
+		writeFileSync(
+			"functions/hello.js",
+			`
+		import { AsyncLocalStorage } from 'node:async_hooks';
+
+    export async function onRequest() {
+			console.log(AsyncLocalStorage);
+      return new Response("Hello from Pages Functions");
+    }
+    `
+		);
+
+		await expect(
+			runWrangler(`pages functions build --outfile=public/_worker.js`)
+		).rejects.toThrowErrorMatchingInlineSnapshot(`
+		"Build failed with 1 error:
+		hello.js:2:36: ERROR: Could not resolve \\"node:async_hooks\\""
+	`);
+	});
 });

packages/wrangler/src/__tests__/publish.test.ts

@@ -6713,6 +6713,78 @@ export default{
 		});
 	});
 
+	describe("`nodejs_compat` compatibility flag", () => {
+		it('when absent, should error on any "external" `node:*` imports', async () => {
+			writeWranglerToml();
+			fs.writeFileSync(
+				"index.js",
+				`
+      import AsyncHooks from 'node:async_hooks';
+      console.log(AsyncHooks);
+      export default {}
+      `
+			);
+			let err: esbuild.BuildFailure | undefined;
+			try {
+				await runWrangler("publish index.js --dry-run"); // expecting this to throw, as node compatibility isn't enabled
+			} catch (e) {
+				err = e as esbuild.BuildFailure;
+			}
+			expect(
+				esbuild.formatMessagesSync(err?.errors ?? [], { kind: "error" }).join()
+			).toMatch(/Could not resolve "node:async_hooks"/);
+		});
+
+		it('when present, should support any "external" `node:*` imports', async () => {
+			writeWranglerToml();
+			fs.writeFileSync(
+				"index.js",
+				`
+      import AsyncHooks from 'node:async_hooks';
+      console.log(AsyncHooks);
+      export default {}
+      `
+			);
+
+			await runWrangler(
+				"publish index.js --dry-run --outdir=dist --compatibility-flag=nodejs_compat"
+			);
+
+			expect(std).toMatchInlineSnapshot(`
+			Object {
+			  "debug": "",
+			  "err": "",
+			  "out": "Total Upload: xx KiB / gzip: xx KiB
+			--dry-run: exiting now.",
+			  "warn": "",
+			}
+		`);
+			expect(fs.readFileSync("dist/index.js", { encoding: "utf-8" })).toContain(
+				`import AsyncHooks from "node:async_hooks";`
+			);
+		});
+
+		it("should conflict with the --node-compat option", async () => {
+			writeWranglerToml();
+			fs.writeFileSync(
+				"index.js",
+				`
+      import AsyncHooks from 'node:async_hooks';
+      console.log(AsyncHooks);
+      export default {}
+      `
+			);
+
+			await expect(
+				runWrangler(
+					"publish index.js --dry-run --outdir=dist --compatibility-flag=nodejs_compat --node-compat"
+				)
+			).rejects.toThrowErrorMatchingInlineSnapshot(
+				`"The \`nodejs_compat\` compatibility flag cannot be used in conjunction with the legacy \`--node-compat\` flag. If you want to use the Workers runtime Node.js compatibility features, please remove the \`--node-compat\` argument from your CLI command or \`node_compat = true\` from your config file."`
+			);
+		});
+	});
+
 	describe("bundle reporter", () => {
 		it("should print the bundle size", async () => {
 			fs.writeFileSync(

packages/wrangler/src/api/pages/publish.tsx

@@ -137,6 +137,11 @@ export async function publish({
 		isProduction = project.production_branch === branch;
 	}
 
+	const deploymentConfig =
+		project.deployment_configs[isProduction ? "production" : "preview"];
+	const nodejsCompat =
+		deploymentConfig.compatibility_flags?.includes("nodejs_compat");
+
 	/**
 	 * Evaluate if this is an Advanced Mode or Pages Functions project. If Advanced Mode, we'll
 	 * go ahead and upload `_worker.js` as is, but if Pages Functions, we need to attempt to build
@@ -176,6 +181,7 @@ export async function publish({
 				routesOutputPath,
 				local: false,
 				d1Databases,
+				nodejsCompat,
 				experimentalWorkerBundle,
 			});
 
@@ -261,6 +267,7 @@ export async function publish({
 				watch: false,
 				onEnd: () => {},
 				betaD1Shims: d1Databases,
+				nodejsCompat,
 				experimentalWorkerBundle,
 			});
 			workerFileContents = readFileSync(outfile, "utf8");

packages/wrangler/src/bundle.ts

@@ -85,6 +85,15 @@ Add "node_compat = true" to your wrangler.toml file to enable Node compatibility
 	}
 }
 
+const nodejsCompatPlugin: esbuild.Plugin = {
+	name: "nodejs_compat Plugin",
+	setup(pluginBuild) {
+		pluginBuild.onResolve({ filter: /node:.*/ }, () => {
+			return { external: true };
+		});
+	},
+};
+
 /**
  * Generate a bundle for the worker identified by the arguments passed in.
  */
@@ -103,6 +112,7 @@ export async function bundleWorker(
 		tsconfig?: string;
 		minify?: boolean;
 		legacyNodeCompat?: boolean;
+		nodejsCompat?: boolean;
 		define: Config["define"];
 		checkFetch: boolean;
 		services?: Config["services"];
@@ -132,6 +142,7 @@ export async function bundleWorker(
 		tsconfig,
 		minify,
 		legacyNodeCompat,
+		nodejsCompat,
 		checkFetch,
 		local,
 		assets,
@@ -363,6 +374,7 @@ export async function bundleWorker(
 			...(legacyNodeCompat
 				? [NodeGlobalsPolyfills({ buffer: true }), NodeModulesPolyfills()]
 				: []),
+			...(nodejsCompat ? [nodejsCompatPlugin] : []),
 			...(plugins || []),
 		],
 		...(jsxFactory && { jsxFactory }),

packages/wrangler/src/dev.tsx

@@ -389,6 +389,7 @@ export async function startDev(args: StartDevOptions) {
 		const {
 			entry,
 			legacyNodeCompat,
+			nodejsCompat,
 			upstreamProtocol,
 			zoneId,
 			host,
@@ -428,6 +429,7 @@ export async function startDev(args: StartDevOptions) {
 					legacyEnv={isLegacyEnv(configParam)}
 					minify={args.minify ?? configParam.minify}
 					legacyNodeCompat={legacyNodeCompat}
+					nodejsCompat={nodejsCompat}
 					build={configParam.build || {}}
 					define={{ ...configParam.define, ...cliDefines }}
 					initialMode={
@@ -524,6 +526,7 @@ export async function startApiDev(args: StartDevOptions) {
 	const {
 		entry,
 		legacyNodeCompat,
+		nodejsCompat,
 		upstreamProtocol,
 		zoneId,
 		host,
@@ -563,6 +566,7 @@ export async function startApiDev(args: StartDevOptions) {
 			legacyEnv: isLegacyEnv(configParam),
 			minify: args.minify ?? configParam.minify,
 			legacyNodeCompat,
+			nodejsCompat,
 			build: configParam.build || {},
 			define: { ...config.define, ...cliDefines },
 			initialMode: args.local ? "local" : "remote",
@@ -749,6 +753,15 @@ async function validateDevServerSettings(
 		);
 	}
 
+	const compatibilityFlags =
+		args.compatibilityFlags ?? config.compatibility_flags;
+	const nodejsCompat = compatibilityFlags?.includes("nodejs_compat");
+	if (legacyNodeCompat && nodejsCompat) {
+		throw new Error(
+			"The `nodejs_compat` compatibility flag cannot be used in conjunction with the legacy `--node-compat` flag. If you want to use the Workers runtime Node.js compatibility features, please remove the `--node-compat` argument from your CLI command or `node_compat = true` from your config file."
+		);
+	}
+
 	if (args.experimentalEnableLocalPersistence) {
 		logger.warn(
 			`--experimental-enable-local-persistence is deprecated.\n` +
@@ -769,6 +782,7 @@ async function validateDevServerSettings(
 		entry,
 		upstreamProtocol,
 		legacyNodeCompat,
+		nodejsCompat,
 		getLocalPort,
 		getInspectorPort,
 		zoneId,

packages/wrangler/src/dev/dev.tsx

@@ -139,6 +139,7 @@ export type DevProps = {
 	usageModel: "bundled" | "unbound" | undefined;
 	minify: boolean | undefined;
 	legacyNodeCompat: boolean | undefined;
+	nodejsCompat: boolean | undefined;
 	build: Config["build"];
 	env: string | undefined;
 	legacyEnv: boolean;
@@ -279,6 +280,7 @@ function DevSession(props: DevSessionProps) {
 		tsconfig: props.tsconfig,
 		minify: props.minify,
 		legacyNodeCompat: props.legacyNodeCompat,
+		nodejsCompat: props.nodejsCompat,
 		betaD1Shims,
 		define: props.define,
 		noBundle: props.noBundle,

packages/wrangler/src/dev/start-server.ts

@@ -99,6 +99,7 @@ export async function startDevServer(
 			tsconfig: props.tsconfig,
 			minify: props.minify,
 			legacyNodeCompat: props.legacyNodeCompat,
+			nodejsCompat: props.nodejsCompat,
 			define: props.define,
 			noBundle: props.noBundle,
 			assets: props.assetsConfig,
@@ -211,6 +212,7 @@ async function runEsbuild({
 	tsconfig,
 	minify,
 	legacyNodeCompat,
+	nodejsCompat,
 	define,
 	noBundle,
 	workerDefinitions,
@@ -234,6 +236,7 @@ async function runEsbuild({
 	tsconfig: string | undefined;
 	minify: boolean | undefined;
 	legacyNodeCompat: boolean | undefined;
+	nodejsCompat: boolean | undefined;
 	noBundle: boolean;
 	workerDefinitions: WorkerRegistry;
 	firstPartyWorkerDevFacade: boolean | undefined;
@@ -267,6 +270,7 @@ async function runEsbuild({
 				tsconfig,
 				minify,
 				legacyNodeCompat,
+				nodejsCompat,
 				define,
 				checkFetch: true,
 				assets: assets && {

packages/wrangler/src/dev/use-esbuild.ts

@@ -31,6 +31,7 @@ export function useEsbuild({
 	tsconfig,
 	minify,
 	legacyNodeCompat,
+	nodejsCompat,
 	betaD1Shims,
 	define,
 	noBundle,
@@ -55,6 +56,7 @@ export function useEsbuild({
 	tsconfig: string | undefined;
 	minify: boolean | undefined;
 	legacyNodeCompat: boolean | undefined;
+	nodejsCompat: boolean | undefined;
 	betaD1Shims?: string[];
 	noBundle: boolean;
 	workerDefinitions: WorkerRegistry;
@@ -122,6 +124,7 @@ export function useEsbuild({
 						tsconfig,
 						minify,
 						legacyNodeCompat,
+						nodejsCompat,
 						betaD1Shims,
 						doBindings: durableObjects.bindings,
 						define,
@@ -189,6 +192,7 @@ export function useEsbuild({
 		noBundle,
 		minify,
 		legacyNodeCompat,
+		nodejsCompat,
 		define,
 		assets,
 		services,

packages/wrangler/src/dev/validate-dev-props.ts

@@ -28,4 +28,13 @@ export function validateDevProps(props: DevProps) {
 			"You cannot configure [data_blobs] with an ES module worker. Instead, import the file directly in your code, and optionally configure `[rules]` in your wrangler.toml"
 		);
 	}
+
+	if (
+		props.compatibilityFlags?.includes("nodejs_compat") &&
+		props.legacyNodeCompat
+	) {
+		throw new Error(
+			"You cannot use the `nodejs_compat` compatibility flag in conjunction with the legacy `--node-compat` flag. If you want to use the new runtime Node.js compatibility features, please remove the `--node-compat` argument from your CLI command or your config file."
+		);
+	}
 }