Support Next.js in autoconfig

dario-piotrowicz · dario-piotrowicz · commit abd3263c7ba3 · 2025-11-28T13:55:10.000Z
diff --git a/.changeset/fair-words-repair.md b/.changeset/fair-words-repair.md
@@ -0,0 +1,5 @@
+---
+"create-cloudflare": patch
+---
+
+Support Next.js in `--experimental` mode
diff --git a/.changeset/yellow-taxes-spend.md b/.changeset/yellow-taxes-spend.md
@@ -0,0 +1,5 @@
+---
+"wrangler": minor
+---
+
+Support Next.js projects in autoconfig
diff --git a/packages/create-cloudflare/e2e/tests/cli/cli.test.ts b/packages/create-cloudflare/e2e/tests/cli/cli.test.ts
@@ -555,7 +555,7 @@ describe("Create Cloudflare CLI", () => {
 					    npm create cloudflare -- --framework next -- --ts
 					    pnpm create cloudflare --framework next -- --ts
 					    Allowed Values:
-					      gatsby, svelte, docusaurus, astro, tanstack-start
+					      gatsby, svelte, docusaurus, astro, tanstack-start, next
 					  --platform=<value>
 					    Whether the application should be deployed to Pages or Workers. This is only applicable for Frameworks templates that support both Pages and Workers.
 					    Allowed Values:
diff --git a/packages/create-cloudflare/e2e/tests/frameworks/test-config.ts b/packages/create-cloudflare/e2e/tests/frameworks/test-config.ts
@@ -745,6 +745,25 @@ function getExperimentalFrameworkTestConfig(
 			nodeCompat: true,
 			verifyTypes: false,
 		},
+		{
+			name: "next",
+			argv: ["--platform", "workers"],
+			flags: ["--yes"],
+			testCommitMessage: true,
+			unsupportedOSs: ["win32"],
+			unsupportedPms: ["npm", "yarn"],
+			verifyDeploy: {
+				route: "/",
+				expectedText: "Generated by create next app",
+			},
+			verifyPreview: {
+				previewArgs: ["--inspector-port=0"],
+				route: "/",
+				expectedText: "Generated by create next app",
+			},
+			nodeCompat: true,
+			verifyTypes: false,
+		},
 	];
 }
 
diff --git a/packages/create-cloudflare/src/templates.ts b/packages/create-cloudflare/src/templates.ts
@@ -32,6 +32,7 @@ import workflowsTemplate from "templates/hello-world-workflows/c3";
 import helloWorldWorkerTemplate from "templates/hello-world/c3";
 import honoTemplate from "templates/hono/c3";
 import nextTemplate from "templates/next/c3";
+import nextExperimentalTemplate from "templates/next/experimental_c3";
 import nuxtTemplate from "templates/nuxt/c3";
 import openapiTemplate from "templates/openapi/c3";
 import preExistingTemplate from "templates/pre-existing/c3";
@@ -241,6 +242,7 @@ export function getFrameworkMap({ experimental = false }): TemplateMap {
 			docusaurus: docusaurusTemplate,
 			astro: astroTemplate,
 			"tanstack-start": tanStackStartTemplate,
+			next: nextExperimentalTemplate,
 		};
 	} else {
 		return {
diff --git a/packages/create-cloudflare/templates/next/experimental_c3.ts b/packages/create-cloudflare/templates/next/experimental_c3.ts
@@ -0,0 +1,26 @@
+import { runFrameworkGenerator } from "frameworks/index";
+import type { TemplateConfig } from "../../src/templates";
+import type { C3Context } from "types";
+
+const generate = async (ctx: C3Context) => {
+	await runFrameworkGenerator(ctx, [
+		ctx.project.name,
+		"--skip-install",
+	]);
+};
+
+const envInterfaceName = "CloudflareEnv";
+const typesPath = "./cloudflare-env.d.ts";
+export default {
+	configVersion: 1,
+	id: "next",
+	frameworkCli: "create-next-app",
+	platform: "workers",
+	displayName: "Next.js",
+	generate,
+	devScript: "dev",
+	previewScript: "preview",
+	deployScript: "deploy",
+	typesPath,
+	envInterfaceName,
+} as TemplateConfig;
diff --git a/packages/wrangler/src/__tests__/autoconfig/details/confirm-auto-config-details.test.ts b/packages/wrangler/src/__tests__/autoconfig/details/confirm-auto-config-details.test.ts
@@ -103,7 +103,7 @@ describe("autoconfig details - confirmAutoConfigDetails()", () => {
 				buildCommand: "astro build",
 				framework: {
 					configured: false,
-					configure: () => ({}),
+					configure: () => ({ wranglerConfig: {} }),
 					name: "astro",
 				},
 				outputDir: "<OUTPUT_DIR>",
diff --git a/packages/wrangler/src/__tests__/autoconfig/details/display-auto-config-details.test.ts b/packages/wrangler/src/__tests__/autoconfig/details/display-auto-config-details.test.ts
@@ -35,7 +35,11 @@ describe("autoconfig details - displayAutoConfigDetails()", () => {
 			configured: false,
 			projectPath: process.cwd(),
 			workerName: "my-astro-app",
-			framework: { name: "Astro", configured: false, configure: () => ({}) },
+			framework: {
+				name: "Astro",
+				configured: false,
+				configure: () => ({ wranglerConfig: {} }),
+			},
 			buildCommand: "astro build",
 			outputDir: "dist",
 		});
diff --git a/packages/wrangler/src/__tests__/autoconfig/run.test.ts b/packages/wrangler/src/__tests__/autoconfig/run.test.ts
@@ -150,7 +150,9 @@ describe("autoconfig (deploy)", () => {
 			});
 			await writeFile(".gitignore", "");
 			const configureSpy = vi.fn(async ({ outputDir }) => ({
-				assets: { directory: outputDir },
+				wranglerConfig: {
+					assets: { directory: outputDir },
+				},
 			}));
 			await run.runAutoConfig({
 				projectPath: process.cwd(),
diff --git a/packages/wrangler/src/autoconfig/errors.ts b/packages/wrangler/src/autoconfig/errors.ts
@@ -0,0 +1,31 @@
+/**
+ * This is used to provide telemetry with a sanitised error
+ * message that could not have any user-identifying information.
+ * Set to `true` to duplicate `message`.
+ *  */
+type TelemetryMessage = {
+	telemetryMessage?: string | true;
+};
+
+/**
+ * Base class for errors where something in a autoconfig frameworks' configuration goes
+ * something wrong. These are not reported to Sentry.
+ */
+export class AutoConfigFrameworkConfigurationError extends Error {
+	telemetryMessage: string | undefined;
+	constructor(
+		message?: string | undefined,
+		options?:
+			| ({
+					cause?: unknown;
+			  } & TelemetryMessage)
+			| undefined
+	) {
+		super(message, options);
+		// Restore prototype chain:
+		// https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#support-for-newtarget
+		Object.setPrototypeOf(this, new.target.prototype);
+		this.telemetryMessage =
+			options?.telemetryMessage === true ? message : options?.telemetryMessage;
+	}
+}
diff --git a/packages/wrangler/src/autoconfig/frameworks/astro.ts b/packages/wrangler/src/autoconfig/frameworks/astro.ts
@@ -3,14 +3,13 @@ import { brandColor, dim } from "@cloudflare/cli/colors";
 import { getPackageManager } from "../../package-manager";
 import { runCommand } from "../c3-vendor/command";
 import { Framework } from ".";
-import type { ConfigurationOptions } from ".";
-import type { RawConfig } from "@cloudflare/workers-utils";
+import type { ConfigurationOptions, ConfigurationResults } from ".";
 
 export class Astro extends Framework {
 	async configure({
 		outputDir,
 		dryRun,
-	}: ConfigurationOptions): Promise<RawConfig> {
+	}: ConfigurationOptions): Promise<ConfigurationResults> {
 		const { npx } = await getPackageManager();
 		if (!dryRun) {
 			await runCommand([npx, "astro", "add", "cloudflare", "-y"], {
@@ -23,11 +22,13 @@ export class Astro extends Framework {
 			writeFileSync("public/.assetsignore", "_worker.js\n_routes.json");
 		}
 		return {
-			main: `${outputDir}/_worker.js/index.js`,
-			compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"],
-			assets: {
-				binding: "ASSETS",
-				directory: outputDir,
+			wranglerConfig: {
+				main: `${outputDir}/_worker.js/index.js`,
+				compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"],
+				assets: {
+					binding: "ASSETS",
+					directory: outputDir,
+				},
 			},
 		};
 	}
diff --git a/packages/wrangler/src/autoconfig/frameworks/get-framework.ts b/packages/wrangler/src/autoconfig/frameworks/get-framework.ts
@@ -1,4 +1,5 @@
 import { Astro } from "./astro";
+import { NextJs } from "./next";
 import { Static } from "./static";
 import { SvelteKit } from "./sveltekit";
 import { TanstackStart } from "./tanstack";
@@ -15,6 +16,8 @@ export function getFramework(detectedFramework?: {
 			return new SvelteKit(detectedFramework.name);
 		case "tanstack-start":
 			return new TanstackStart(detectedFramework.name);
+		case "next":
+			return new NextJs(detectedFramework.name);
 		default:
 			return new Static(detectedFramework?.name);
 	}
diff --git a/packages/wrangler/src/autoconfig/frameworks/index.ts b/packages/wrangler/src/autoconfig/frameworks/index.ts
@@ -6,6 +6,12 @@ export type ConfigurationOptions = {
 	workerName: string;
 	dryRun: boolean;
 };
+
+export type ConfigurationResults = {
+	wranglerConfig: RawConfig;
+	buildCommand?: string;
+};
+
 export abstract class Framework {
 	constructor(public name: string = "Static") {}
 
@@ -21,7 +27,7 @@ export abstract class Framework {
 
 	abstract configure(
 		options: ConfigurationOptions
-	): Promise<RawConfig> | RawConfig;
+	): Promise<ConfigurationResults> | ConfigurationResults;
 
 	configurationDescription?: string;
 }
diff --git a/packages/wrangler/src/autoconfig/frameworks/next.ts b/packages/wrangler/src/autoconfig/frameworks/next.ts
@@ -0,0 +1,130 @@
+import { statSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { brandColor, dim } from "@cloudflare/cli/colors";
+import { spinner } from "@cloudflare/cli/interactive";
+import { getPackageManager } from "../../package-manager";
+import { dedent } from "../../utils/dedent";
+import { installPackages } from "../c3-vendor/packages";
+import { AutoConfigFrameworkConfigurationError } from "../errors";
+import { appendToGitIgnore } from "../git";
+import { usesTypescript } from "../uses-typescript";
+import { Framework } from ".";
+import type { ConfigurationOptions, ConfigurationResults } from ".";
+
+export class NextJs extends Framework {
+	preview = "opennextjs-cloudflare build && opennextjs-cloudflare preview";
+	deploy = "opennextjs-cloudflare build && opennextjs-cloudflare deploy";
+
+	async configure({
+		dryRun,
+		projectPath,
+	}: ConfigurationOptions): Promise<ConfigurationResults> {
+		const usesTs = usesTypescript(projectPath);
+
+		const nextConfigPath = probeForNextConfigPath(usesTs);
+		if (!nextConfigPath) {
+			throw new AutoConfigFrameworkConfigurationError(
+				"No Next.js configuration file could be detected. Note: only next.config.ts and next.config.mjs files are supported."
+			);
+		}
+
+		if (!dryRun) {
+			await installPackages(["@opennextjs/cloudflare@^1.12.0"], {
+				startText: "Installing @opennextjs/cloudflare adapter",
+				doneText: `${brandColor("installed")}`,
+			});
+
+			await updateNextConfig(nextConfigPath);
+
+			await createOpenNextConfigFile(projectPath);
+
+			await appendToGitIgnore(
+				projectPath,
+				dedent`
+				# OpenNext
+				.open-next
+				`,
+				{
+					startText: "Adding open-next section to .gitignore file",
+					doneText: `${brandColor(`added`)} open-next section to .gitignore file`,
+				}
+			);
+		}
+
+		const { npx } = await getPackageManager();
+
+		return {
+			wranglerConfig: {
+				main: ".open-next/worker.js",
+				compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"],
+				assets: {
+					binding: "ASSETS",
+					directory: ".open-next/assets",
+				},
+			},
+			buildCommand: `${npx} @opennextjs/cloudflare build`,
+		};
+	}
+
+	configurationDescription = "Configuring project for Next.js with OpenNext";
+}
+
+function probeForNextConfigPath(usesTs: boolean): string | undefined {
+	const pathsToProbe = [
+		...(usesTs ? ["next.config.ts"] : []),
+		"next.config.mjs",
+	];
+
+	for (const path of pathsToProbe) {
+		const stats = statSync(path, {
+			throwIfNoEntry: false,
+		});
+		if (stats?.isFile()) {
+			return path;
+		}
+	}
+}
+
+async function updateNextConfig(nextConfigPath: string) {
+	const s = spinner();
+
+	s.start(`Updating \`${nextConfigPath}\``);
+
+	const configContent = await readFile(nextConfigPath);
+
+	const updatedConfigFile =
+		configContent +
+		`
+		// added by create cloudflare to enable calling \`getCloudflareContext()\` in \`next dev\`
+		import { initOpenNextCloudflareForDev } from '@opennextjs/cloudflare';
+		initOpenNextCloudflareForDev();
+		`.replace(/\n\t*/g, "\n");
+
+	await writeFile(nextConfigPath, updatedConfigFile);
+
+	s.stop(`${brandColor(`updated`)} ${dim(`\`${nextConfigPath}\``)}`);
+}
+
+async function createOpenNextConfigFile(projectPath: string) {
+	const s = spinner();
+
+	s.start("Creating open-next.config.ts file");
+
+	await writeFile(
+		// TODO: this always saves the file as open-next.config.ts, is a js alternative also supported?
+		//       (since the project might not be using TypeScript)
+		`${projectPath}/open-next.config.ts`,
+		dedent`import { defineCloudflareConfig } from "@opennextjs/cloudflare";
+
+				export default defineCloudflareConfig({
+				// Uncomment to enable R2 cache,
+				// It should be imported as:
+				// \`import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";\`
+				// See https://opennext.js.org/cloudflare/caching for more details
+				// incrementalCache: r2IncrementalCache,
+				});
+			`
+	);
+
+	s.stop(`${brandColor("created")} open-next.config.ts file`);
+}
diff --git a/packages/wrangler/src/autoconfig/frameworks/static.ts b/packages/wrangler/src/autoconfig/frameworks/static.ts
@@ -1,14 +1,13 @@
 import { Framework } from ".";
-import type { ConfigurationOptions } from ".";
-import type { RawConfig } from "@cloudflare/workers-utils";
+import type { ConfigurationOptions, ConfigurationResults } from ".";
 
 export class Static extends Framework {
-	configure({
-		outputDir,
-	}: ConfigurationOptions): Promise<RawConfig> | RawConfig {
+	configure({ outputDir }: ConfigurationOptions): ConfigurationResults {
 		return {
-			assets: {
-				directory: outputDir,
+			wranglerConfig: {
+				assets: {
+					directory: outputDir,
+				},
 			},
 		};
 	}
diff --git a/packages/wrangler/src/autoconfig/frameworks/sveltekit.ts b/packages/wrangler/src/autoconfig/frameworks/sveltekit.ts
diff --git a/packages/wrangler/src/autoconfig/git.ts b/packages/wrangler/src/autoconfig/git.ts
diff --git a/packages/wrangler/src/autoconfig/run.ts b/packages/wrangler/src/autoconfig/run.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"create-cloudflare": patch
 +---
++
 +Support Next.js in `--experimental` mode