Support packages and virtual modules in the main field of the Worker config (#10212)

jamesopstad · web-flow · commit 0837a8d4e406 · 2025-09-10T22:25:48.000+01:00
* Add experimental.preserveOriginalMain options to readConfig

* Add main-resolution playground

* Add tests

* Support virtual modules and package exports in main field

* Use virtual module for injecting nodejs_compat polyfills

* Add changesets

* PR feedback

* Remove experimental from preserveOriginalMain naming
diff --git a/.changeset/eighty-nights-vanish.md b/.changeset/eighty-nights-vanish.md
@@ -0,0 +1,5 @@
+---
+"wrangler": patch
+---
+
+Add `preserveOriginalMain` option to `unstable_readConfig`. This will pass the original `main` value through, without converting it to an absolute path.
diff --git a/.changeset/gold-dodos-stick.md b/.changeset/gold-dodos-stick.md
@@ -0,0 +1,5 @@
+---
+"@cloudflare/vite-plugin": minor
+---
+
+Support packages and virtual modules in the `main` field of the Worker config. The primary use case is to enable users to directly provide a file exported by a framework as the Worker entry module.
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/__tests__/main-resolution.spec.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/__tests__/main-resolution.spec.ts
@@ -0,0 +1,9 @@
+import { expect, test } from "vitest";
+import { getJsonResponse } from "../../__test-utils__";
+
+test("resolves `main` relative to a root level Worker config", async () => {
+	expect(await getJsonResponse()).toEqual({
+		entry: "Root config",
+		imported: "Root config import",
+	});
+});
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/__tests__/nested-config/main-resolution.spec.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/__tests__/nested-config/main-resolution.spec.ts
@@ -0,0 +1,9 @@
+import { expect, test } from "vitest";
+import { getJsonResponse } from "../../../__test-utils__";
+
+test("resolves `main` relative to a nested Worker config", async () => {
+	expect(await getJsonResponse()).toEqual({
+		entry: "Nested config",
+		imported: "Nested config import",
+	});
+});
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/__tests__/package-export-main/main-resolution.spec.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/__tests__/package-export-main/main-resolution.spec.ts
@@ -0,0 +1,6 @@
+import { expect, test } from "vitest";
+import { getTextResponse } from "../../../__test-utils__";
+
+test("supports package exports in the `main` field", async () => {
+	expect(await getTextResponse()).toBe("Package export as Worker entry file");
+});
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/__tests__/virtual-module-main/main-resolution.spec.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/__tests__/virtual-module-main/main-resolution.spec.ts
@@ -0,0 +1,6 @@
+import { expect, test } from "vitest";
+import { getTextResponse } from "../../../__test-utils__";
+
+test("supports virtual modules in the `main` field", async () => {
+	expect(await getTextResponse()).toBe("Virtual module as Worker entry file");
+});
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/nested-config/another/another.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/nested-config/another/another.ts
@@ -0,0 +1 @@
+export const text = "Nested config import";
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/nested-config/index.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/nested-config/index.ts
@@ -0,0 +1,7 @@
+import { text } from "./another/another";
+
+export default {
+	async fetch() {
+		return Response.json({ entry: "Nested config", imported: text });
+	},
+};
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/nested-config/wrangler.jsonc b/packages/vite-plugin-cloudflare/playground/main-resolution/nested-config/wrangler.jsonc
@@ -0,0 +1,5 @@
+{
+	"name": "worker",
+	"main": "./index.ts",
+	"compatibility_date": "2024-12-30",
+}
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/package.json b/packages/vite-plugin-cloudflare/playground/main-resolution/package.json
@@ -0,0 +1,26 @@
+{
+	"name": "@playground/main-resolution",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build",
+		"build:nested-config": "vite build -c vite.config.nested-config.ts",
+		"build:package-export-main": "vite build -c vite.config.package-export-main.ts",
+		"build:virtual-module-main": "vite build -c vite.config.virtual-module-main.ts",
+		"check:types": "tsc --build",
+		"dev": "vite dev",
+		"dev:nested-config": "vite dev -c vite.config.nested-config.ts",
+		"dev:package-export-main": "vite dev -c vite.config.package-export-main.ts",
+		"dev:virtual-module-main": "vite dev -c vite.config.virtual-module-main.ts",
+		"preview": "vite preview"
+	},
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "workspace:*",
+		"@cloudflare/workers-tsconfig": "workspace:*",
+		"@cloudflare/workers-types": "catalog:default",
+		"@playground/main-resolution-package": "file:./package",
+		"typescript": "catalog:default",
+		"vite": "catalog:vite-plugin",
+		"wrangler": "workspace:*"
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/package/entry.js b/packages/vite-plugin-cloudflare/playground/main-resolution/package/entry.js
@@ -0,0 +1,5 @@
+export default {
+	fetch() {
+		return new Response("Package export as Worker entry file");
+	},
+};
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/package/index.js b/packages/vite-plugin-cloudflare/playground/main-resolution/package/index.js
@@ -0,0 +1 @@
+export const name = "Root export";
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/package/package.json b/packages/vite-plugin-cloudflare/playground/main-resolution/package/package.json
@@ -0,0 +1,10 @@
+{
+	"name": "@playground/main-resolution-package",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./index.js",
+		"./entry": "./entry.js"
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/src/another/another.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/src/another/another.ts
@@ -0,0 +1 @@
+export const text = "Root config import";
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/src/index.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/src/index.ts
@@ -0,0 +1,7 @@
+import { text } from "./another/another";
+
+export default {
+	async fetch() {
+		return Response.json({ entry: "Root config", imported: text });
+	},
+};
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/tsconfig.json b/packages/vite-plugin-cloudflare/playground/main-resolution/tsconfig.json
@@ -0,0 +1,7 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.worker.json" }
+	]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/tsconfig.node.json b/packages/vite-plugin-cloudflare/playground/main-resolution/tsconfig.node.json
@@ -0,0 +1,10 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/base.json"],
+	"include": [
+		"vite.config.ts",
+		"vite.config.nested-config.ts",
+		"vite.config.package-export-main.ts",
+		"vite.config.virtual-module-main.ts",
+		"__tests__"
+	]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/tsconfig.worker.json b/packages/vite-plugin-cloudflare/playground/main-resolution/tsconfig.worker.json
@@ -0,0 +1,4 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/worker.json"],
+	"include": ["src", "nested-config"]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/turbo.json b/packages/vite-plugin-cloudflare/playground/main-resolution/turbo.json
@@ -0,0 +1,9 @@
+{
+	"$schema": "http://turbo.build/schema.json",
+	"extends": ["//"],
+	"tasks": {
+		"build": {
+			"outputs": ["dist/**"]
+		}
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/vite.config.nested-config.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/vite.config.nested-config.ts
@@ -0,0 +1,12 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [
+		cloudflare({
+			inspectorPort: false,
+			persistState: false,
+			configPath: "./nested-config/wrangler.jsonc",
+		}),
+	],
+});
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/vite.config.package-export-main.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/vite.config.package-export-main.ts
@@ -0,0 +1,12 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [
+		cloudflare({
+			inspectorPort: false,
+			persistState: false,
+			configPath: "./wrangler.package-export-main.jsonc",
+		}),
+	],
+});
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/vite.config.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/vite.config.ts
@@ -0,0 +1,18 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	environments: {
+		worker: {
+			build: {
+				rollupOptions: {
+					output: {
+						// This is to test that entry file names with custom file extensions are correctly populated in the `main` field of the output `wrangler.json`
+						entryFileNames: "[name].mjs",
+					},
+				},
+			},
+		},
+	},
+	plugins: [cloudflare({ inspectorPort: false, persistState: false })],
+});
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/vite.config.virtual-module-main.ts b/packages/vite-plugin-cloudflare/playground/main-resolution/vite.config.virtual-module-main.ts
@@ -0,0 +1,31 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [
+		{
+			name: "virtual-module-plugin",
+			resolveId(source) {
+				if (source === "virtual:entry") {
+					return `\0${source}`;
+				}
+			},
+			load(id) {
+				if (id === "\0virtual:entry") {
+					return `
+export default {
+	fetch() {
+		return new Response("Virtual module as Worker entry file");
+	}
+}
+					`;
+				}
+			},
+		},
+		cloudflare({
+			inspectorPort: false,
+			persistState: false,
+			configPath: "./wrangler.virtual-module-main.jsonc",
+		}),
+	],
+});
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/wrangler.jsonc b/packages/vite-plugin-cloudflare/playground/main-resolution/wrangler.jsonc
@@ -0,0 +1,6 @@
+{
+	"name": "worker",
+	// Omit leading `./` to test that `main` can still be resolved
+	"main": "src/index.ts",
+	"compatibility_date": "2024-12-30",
+}
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/wrangler.package-export-main.jsonc b/packages/vite-plugin-cloudflare/playground/main-resolution/wrangler.package-export-main.jsonc
@@ -0,0 +1,7 @@
+{
+	"name": "worker",
+	"main": "@playground/main-resolution-package/entry",
+	"compatibility_date": "2024-12-30",
+	// Enable `nodejs_compat` to ensure there are no errors adding the polyfills
+	"compatibility_flags": ["nodejs_compat"],
+}
diff --git a/packages/vite-plugin-cloudflare/playground/main-resolution/wrangler.virtual-module-main.jsonc b/packages/vite-plugin-cloudflare/playground/main-resolution/wrangler.virtual-module-main.jsonc
@@ -0,0 +1,5 @@
+{
+	"name": "worker",
+	"main": "virtual:entry",
+	"compatibility_date": "2024-12-30",
+}
diff --git a/packages/vite-plugin-cloudflare/src/__tests__/fixtures/incorrect-dir-main-wrangler.jsonc b/packages/vite-plugin-cloudflare/src/__tests__/fixtures/incorrect-dir-main-wrangler.jsonc
diff --git a/packages/vite-plugin-cloudflare/src/__tests__/get-worker-config.spec.ts b/packages/vite-plugin-cloudflare/src/__tests__/get-worker-config.spec.ts
@@ -170,21 +170,5 @@ describe("getWorkerConfig", () => {
 				/The provided Wrangler config main field \(.*?index\.ts\) doesn't point to an existing file/
 			);
 		});
-
-		test("should throw if the provided main config doesn't point to an existing file", () => {
-			expect(() =>
-				getWorkerConfig(
-					fileURLToPath(
-						new URL(
-							"fixtures/incorrect-dir-main-wrangler.jsonc",
-							import.meta.url
-						)
-					),
-					undefined
-				)
-			).toThrowError(
-				/The provided Wrangler config main field \(.*?fixtures\) points to a directory, it needs to point to a file instead/
-			);
-		});
 	});
 });
diff --git a/packages/vite-plugin-cloudflare/src/cloudflare-environment.ts b/packages/vite-plugin-cloudflare/src/cloudflare-environment.ts
@@ -1,7 +1,13 @@
 import assert from "node:assert";
 import * as util from "node:util";
 import * as vite from "vite";
-import { INIT_PATH, UNKNOWN_HOST, WORKER_ENTRY_PATH_HEADER } from "./shared";
+import { MAIN_ENTRY_NAME } from "./constants";
+import {
+	INIT_PATH,
+	UNKNOWN_HOST,
+	VIRTUAL_WORKER_ENTRY,
+	WORKER_ENTRY_PATH_HEADER,
+} from "./shared";
 import { getOutputDirectory } from "./utils";
 import type { WorkerConfig, WorkersResolvedConfig } from "./plugin-config";
 import type { Fetcher } from "@cloudflare/workers-types/experimental";
@@ -167,7 +173,9 @@ export function createCloudflareEnvironmentOptions({
 			copyPublicDir: false,
 			ssr: true,
 			rollupOptions: {
-				input: workerConfig.main,
+				input: {
+					[MAIN_ENTRY_NAME]: VIRTUAL_WORKER_ENTRY,
+				},
 				// workerd checks the types of the exports so we need to ensure that additional exports are not added to the entry module
 				preserveEntrySignatures: "strict",
 				// rolldown-only option
diff --git a/packages/vite-plugin-cloudflare/src/constants.ts b/packages/vite-plugin-cloudflare/src/constants.ts
@@ -3,6 +3,15 @@ export const ASSET_WORKER_NAME = "__asset-worker__";
 export const VITE_PROXY_WORKER_NAME = "__vite_proxy_worker__";
 export const ASSET_WORKERS_COMPATIBILITY_DATE = "2024-10-04";
 
+export const ENTRY_MODULE_EXTENSIONS = [
+	".js",
+	".mjs",
+	".ts",
+	".mts",
+	".jsx",
+	".tsx",
+];
+
 export const ADDITIONAL_MODULE_TYPES = [
 	"CompiledWasm",
 	"Data",
@@ -16,6 +25,13 @@ export const DEFAULT_INSPECTOR_PORT = 9229;
 
 export const DEBUG_PATH = "/__debug";
 
+export const MAIN_ENTRY_NAME = "index";
+
+// virtual modules
+export const virtualPrefix = "virtual:cloudflare/";
+export const VIRTUAL_USER_ENTRY = `${virtualPrefix}user-entry`;
+export const VIRTUAL_NODEJS_COMPAT_ENTRY = `${virtualPrefix}nodejs-compat-entry`;
+
 export const kRequestType = Symbol("kRequestType");
 
 declare module "http" {
diff --git a/packages/vite-plugin-cloudflare/src/index.ts b/packages/vite-plugin-cloudflare/src/index.ts
diff --git a/packages/vite-plugin-cloudflare/src/nodejs-compat.ts b/packages/vite-plugin-cloudflare/src/nodejs-compat.ts
diff --git a/packages/vite-plugin-cloudflare/src/runner-worker/module-runner.ts b/packages/vite-plugin-cloudflare/src/runner-worker/module-runner.ts
diff --git a/packages/vite-plugin-cloudflare/src/shared.ts b/packages/vite-plugin-cloudflare/src/shared.ts
diff --git a/packages/vite-plugin-cloudflare/src/workers-configs.ts b/packages/vite-plugin-cloudflare/src/workers-configs.ts
diff --git a/packages/wrangler/src/config/index.ts b/packages/wrangler/src/config/index.ts
diff --git a/packages/wrangler/src/config/validation.ts b/packages/wrangler/src/config/validation.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"wrangler": patch
 +---
++
 +Add `preserveOriginalMain` option to `unstable_readConfig`. This will pass the original `main` value through, without converting it to an absolute path.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+export const text = "Nested config import";`