Throw a helpful error if Vite can't resolve the main entrypoint (#11466)

* Throw a helpful error if Vite can't resolve the main entrypoint

* Apply suggestions from code review

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

* Format

---------

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

Author: ascorbic

.changeset/breezy-dots-visit.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/vite-plugin": patch
+---
+
+Throw a more helpful error message when a Worker's entry module can't be resolved

packages/vite-plugin-cloudflare/e2e/fixtures/unresolved-main/package.json

@@ -0,0 +1,12 @@
+{
+	"name": "@cloudflare/vite-plugin-e2e-unresolved-main",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"dev": "vite dev"
+	},
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "*",
+		"vite": "^6.1.0"
+	}
+}

packages/vite-plugin-cloudflare/e2e/fixtures/unresolved-main/vite.config.ts

@@ -0,0 +1,6 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [cloudflare({ inspectorPort: false, persistState: false })],
+});

packages/vite-plugin-cloudflare/e2e/fixtures/unresolved-main/wrangler.jsonc

@@ -0,0 +1,5 @@
+{
+	"name": "worker",
+	"main": "nonexistent-bare-module",
+	"compatibility_date": "2025-11-28",
+}

packages/vite-plugin-cloudflare/e2e/unresolved-main.test.ts

@@ -0,0 +1,16 @@
+import { describe, test } from "vitest";
+import { runLongLived, seed } from "./helpers";
+
+describe("unresolved main entry file", () => {
+	const projectPath = seed("unresolved-main", "pnpm");
+
+	test("throws an error when the main entry file cannot be resolved", async ({
+		expect,
+	}) => {
+		const proc = await runLongLived("pnpm", "dev", projectPath);
+		expect(await proc.exitCode).not.toBe(0);
+		expect(proc.stderr).toContain(
+			'Failed to resolve main entry file "nonexistent-bare-module"'
+		);
+	});
+});

packages/vite-plugin-cloudflare/src/plugins/virtual-modules.ts

@@ -17,16 +17,21 @@ export const virtualModulesPlugin = createPlugin("virtual-modules", (ctx) => {
 		applyToEnvironment(environment) {
 			return ctx.getWorkerConfig(environment.name) !== undefined;
 		},
-		resolveId(source) {
+		async resolveId(source) {
 			if (source === VIRTUAL_WORKER_ENTRY || source === VIRTUAL_EXPORT_TYPES) {
 				return `\0${source}`;
 			}
 
 			if (source === VIRTUAL_USER_ENTRY) {
 				const workerConfig = ctx.getWorkerConfig(this.environment.name);
 				assert(workerConfig, "Expected `workerConfig` to be defined");
-
-				return this.resolve(workerConfig.main);
+				const main = await this.resolve(workerConfig.main);
+				if (!main) {
+					throw new Error(
+						`Failed to resolve main entry file "${workerConfig.main}" for environment "${this.environment.name}"`
+					);
+				}
+				return main;
 			}
 		},
 		load(id) {