[autoconfig] Bump Next.js minimum versions and provide an automatic upgrade path

Author: ajhawkings

.changeset/autoconfig-bump-next-and-auto-upgrade.md

@@ -0,0 +1,14 @@
+---
+"@cloudflare/autoconfig": minor
+"wrangler": minor
+---
+
+Bump Next.js minimum versions and provide an automatic upgrade path
+
+`@opennextjs/cloudflare` declares a Next.js peer range of `>=15.5.21 <16 || >=16.2.11`, so projects on earlier 15.x or 16.x releases sit outside the versions the adapter supports.
+
+Autoconfig previously ran `@opennextjs/cloudflare migrate --force-install`. That flag just passes `--force` to the package manager. The peer dependency error becomes a warning buried in the install output, Next.js stays on its unsupported version, and setup finishes with a success message.
+
+Autoconfig now recognises the supported floors and offers to update an unsupported project in place, staying within its existing major version. The update is listed in the setup summary before you confirm, and is applied before any other project changes are made. `--force-install` is no longer passed, so a real dependency conflict is reported rather than forced.
+
+Two cases are not updated automatically and ask you to update Next.js yourself. Next.js 14 now falls outside the adapter's peer range entirely, and Next.js 15.0.x cannot be updated in place because `create-next-app` pinned React to a 19 prerelease before Next.js 15.1, which no supported Next.js version accepts as a peer.

packages/autoconfig/package.json

@@ -38,11 +38,13 @@
 		"@netlify/build-info": "^10.5.1",
 		"@types/esprima": "^4.0.3",
 		"@types/node": "catalog:default",
+		"@types/semver": "^7.5.1",
 		"chalk": "catalog:default",
 		"empathic": "^2.0.0",
 		"esprima": "4.0.1",
 		"recast": "0.23.11",
 		"semiver": "^1.1.0",
+		"semver": "^7.7.1",
 		"ts-dedent": "^2.2.0",
 		"tsup": "8.3.0",
 		"typescript": "catalog:default",

packages/autoconfig/src/frameworks/all-frameworks.ts

@@ -75,10 +75,19 @@ export const allKnownFrameworks = [
 		class: NextJs,
 		frameworkPackageInfo: {
 			name: "next",
-			// 14.2.35 is the earliest version of Next.js officially supported by open-next
-			// see: https://github.com/cloudflare/workers-sdk/pull/11704#discussion_r2634519440
-			minimumVersion: "14.2.35",
+			// 15.5.21 is the earliest version of Next.js officially supported by open-next
+			// see: https://github.com/opennextjs/opennextjs-cloudflare/pull/1313
+			minimumVersion: "15.5.21",
 			maximumKnownMajorVersion: "16",
+			// Next.js 15 and 16 installations that OpenNext doesn't support are upgraded in
+			// place, staying within their existing major version.
+			// 15.0.x is deliberately excluded: `create-next-app` pinned React to a 19 prerelease
+			// until Next.js 15.1, which no supported Next.js version accepts as a peer, so the
+			// upgrade cannot succeed without the user changing React first.
+			upgradeRequired: {
+				">=15.1.0 <15.5.21": "15.5.21",
+				">=16 <16.2.11": "16.2.11",
+			},
 		},
 		supported: true,
 	},

packages/autoconfig/src/frameworks/framework-class.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import semiver from "semiver";
+import semverSatisfies from "semver/functions/satisfies.js";
 import { AutoConfigFrameworkConfigurationError } from "../errors";
 import { getInstalledPackageVersion } from "./utils/packages";
 import type { AutoConfigFrameworkPackageInfo, FrameworkInfo } from ".";
@@ -35,22 +36,44 @@ export abstract class Framework {
 
 	configurationDescription?: string;
 
+	/**
+	 * Upgrades the framework to a version that autoconfig supports.
+	 *
+	 * Only called for installed versions matched by the package's `upgradeRequired` ranges, so
+	 * frameworks that don't declare any never need to implement this.
+	 *
+	 * @param _options - The installed version, the version to upgrade to, the package
+	 * manager, and the workspace root flag.
+	 */
+	upgradeFrameworkVersion(
+		_options: FrameworkVersionUpgradeOptions
+	): Promise<void> {
+		throw new AutoConfigFrameworkConfigurationError(
+			`${this.name} requires an upgrade before it can be automatically configured, but autoconfig cannot upgrade it automatically.`,
+			{ telemetryMessage: "autoconfig framework version upgrade unavailable" }
+		);
+	}
+
 	/**
 	 * Validates the installed framework version against the supported range and
 	 * stores it for later access via the `frameworkVersion` getter.
 	 * Warns via the context logger if the version exceeds `maximumKnownMajorVersion`.
 	 *
+	 * Versions matched by `upgradeRequired` are returned as an upgrade for the caller to apply,
+	 * rather than being rejected for being below `minimumVersion`.
+	 *
 	 * @param projectPath - Path to the project root used to resolve the installed version.
 	 * @param frameworkPackageInfo - Package metadata including name and version bounds.
 	 * @param context - The autoconfig context providing logger and other dependencies.
 	 * @throws {AssertionError} If the installed version cannot be determined.
-	 * @throws {AutoConfigFrameworkConfigurationError} If the version is below `minimumVersion`.
+	 * @throws {AutoConfigFrameworkConfigurationError} If the version is below `minimumVersion` and no upgrade is available.
+	 * @returns The upgrade needed to reach a supported version, or `undefined` if none is needed.
 	 */
 	validateFrameworkVersion(
 		projectPath: string,
 		frameworkPackageInfo: AutoConfigFrameworkPackageInfo,
 		context: AutoConfigContext
-	) {
+	): FrameworkVersionUpgrade | undefined {
 		const frameworkVersion = getInstalledPackageVersion(
 			frameworkPackageInfo.name,
 			projectPath
@@ -61,6 +84,19 @@ export abstract class Framework {
 			`Unable to detect the version of the \`${frameworkPackageInfo.name}\` package`
 		);
 
+		for (const [versionRange, upgradeTo] of Object.entries(
+			frameworkPackageInfo.upgradeRequired ?? {}
+		)) {
+			if (
+				semverSatisfies(frameworkVersion, versionRange, {
+					includePrerelease: true,
+				})
+			) {
+				this.#frameworkVersion = frameworkVersion;
+				return { installedVersion: frameworkVersion, upgradeTo };
+			}
+		}
+
 		if (semiver(frameworkVersion, frameworkPackageInfo.minimumVersion) < 0) {
 			throw new AutoConfigFrameworkConfigurationError(
 				`The version of ${this.name} used in the project (${JSON.stringify(
@@ -89,6 +125,14 @@ export abstract class Framework {
 	}
 }
 
+export type FrameworkVersionUpgrade = {
+	installedVersion: string;
+	upgradeTo: string;
+};
+
+export type FrameworkVersionUpgradeOptions = FrameworkVersionUpgrade &
+	Pick<ConfigurationOptions, "isWorkspaceRoot" | "packageManager">;
+
 export type ConfigurationOptions = {
 	outputDir: string;
 	projectPath: string;

packages/autoconfig/src/frameworks/index.ts

@@ -80,4 +80,9 @@ export type AutoConfigFrameworkPackageInfo = {
 	minimumVersion: string;
 	/** The latest major version of the package/framework that autoconfig supports  */
 	maximumKnownMajorVersion: string;
+	/**
+	 * Maps ranges of installed versions that autoconfig can upgrade in place to the version each
+	 * range should be upgraded to. Ranges are checked in order, and the first match wins.
+	 */
+	upgradeRequired?: Record<string, string>;
 };

packages/autoconfig/src/frameworks/next.ts

@@ -1,11 +1,26 @@
+import { brandColor, dim } from "@cloudflare/cli-shared-helpers/colors";
 import { runCommand } from "@cloudflare/cli-shared-helpers/command";
+import { installPackages } from "@cloudflare/cli-shared-helpers/packages";
 import { Framework } from "./framework-class";
 import type {
 	ConfigurationOptions,
 	ConfigurationResults,
+	FrameworkVersionUpgradeOptions,
 } from "./framework-class";
 
 export class NextJs extends Framework {
+	async upgradeFrameworkVersion({
+		upgradeTo,
+		packageManager,
+		isWorkspaceRoot,
+	}: FrameworkVersionUpgradeOptions): Promise<void> {
+		await installPackages(packageManager.type, [`next@${upgradeTo}`], {
+			isWorkspaceRoot,
+			startText: `Updating Next.js to ${upgradeTo}`,
+			doneText: `${brandColor("updated")} ${dim(`Next.js to ${upgradeTo}`)}`,
+		});
+	}
+
 	async configure({
 		dryRun,
 		projectPath,
@@ -14,20 +29,9 @@ export class NextJs extends Framework {
 		const { npx, dlx } = packageManager;
 
 		if (!dryRun) {
-			await runCommand(
-				[
-					...dlx,
-					"@opennextjs/cloudflare",
-					"migrate",
-					// Note: we force-install so that even if an incompatible version of
-					//       Next.js is used this installation still succeeds, moving users
-					//       (hopefully) in right direction (instead of failing at this step)
-					"--force-install",
-				],
-				{
-					cwd: projectPath,
-				}
-			);
+			await runCommand([...dlx, "@opennextjs/cloudflare", "migrate"], {
+				cwd: projectPath,
+			});
 		}
 
 		return {

packages/autoconfig/src/run.ts

@@ -17,6 +17,7 @@ import {
 	confirmAutoConfigDetails,
 	displayAutoConfigDetails,
 } from "./details";
+import { AutoConfigFrameworkConfigurationError } from "./errors";
 import {
 	isFrameworkSupported,
 	isKnownFramework,
@@ -110,13 +111,13 @@ export async function runAutoConfig(
 	const frameworkPackageInfo = getFrameworkPackageInfo(
 		autoConfigDetails.framework.id
 	);
-	if (frameworkPackageInfo) {
-		autoConfigDetails.framework.validateFrameworkVersion(
-			autoConfigDetails.projectPath,
-			frameworkPackageInfo,
-			context
-		);
-	}
+	const frameworkVersionUpgrade = frameworkPackageInfo
+		? autoConfigDetails.framework.validateFrameworkVersion(
+				autoConfigDetails.projectPath,
+				frameworkPackageInfo,
+				context
+			)
+		: undefined;
 
 	const dryRunConfigurationResults =
 		await autoConfigDetails.framework.configure({
@@ -151,7 +152,12 @@ export async function runAutoConfig(
 				`${npx} wrangler versions upload`,
 		},
 		context,
-		dryRunConfigurationResults.packageJsonScriptsOverrides
+		dryRunConfigurationResults.packageJsonScriptsOverrides,
+		frameworkVersionUpgrade
+			? `Upgrade ${autoConfigDetails.framework.name} from ${JSON.stringify(
+					frameworkVersionUpgrade.installedVersion
+				)} to ${JSON.stringify(frameworkVersionUpgrade.upgradeTo)}`
+			: undefined
 	);
 
 	if (
@@ -174,6 +180,34 @@ export async function runAutoConfig(
 		return autoConfigSummary;
 	}
 
+	if (frameworkVersionUpgrade) {
+		await autoConfigDetails.framework.upgradeFrameworkVersion({
+			...frameworkVersionUpgrade,
+			packageManager,
+			isWorkspaceRoot,
+		});
+
+		assert(frameworkPackageInfo);
+		// Hold the newly installed version to the same bounds as any other supported version
+		const remainingUpgrade =
+			autoConfigDetails.framework.validateFrameworkVersion(
+				autoConfigDetails.projectPath,
+				frameworkPackageInfo,
+				context
+			);
+
+		if (remainingUpgrade) {
+			throw new AutoConfigFrameworkConfigurationError(
+				`${autoConfigDetails.framework.name} was updated to ${JSON.stringify(
+					frameworkVersionUpgrade.upgradeTo
+				)}, but the version installed in the project is still ${JSON.stringify(
+					remainingUpgrade.installedVersion
+				)}. Update it manually and try again.`,
+				{ telemetryMessage: "autoconfig framework version upgrade incomplete" }
+			);
+		}
+	}
+
 	logger.debug(
 		`Running autoconfig with:\n${JSON.stringify(autoConfigDetails, null, 2)}...`
 	);
@@ -320,6 +354,7 @@ async function saveWranglerJsonc(
  * @param projectCommands - The build, deploy, and version commands for the project.
  * @param context - The autoconfig context providing logger and other dependencies.
  * @param packageJsonScriptsOverrides - Optional overrides for package.json script entries.
+ * @param frameworkVersionUpgradeDescription - Optional framework upgrade shown before other setup operations.
  * @returns A summary object describing all planned operations.
  */
 export async function buildOperationsSummary(
@@ -333,7 +368,8 @@ export async function buildOperationsSummary(
 		version?: string;
 	},
 	context: AutoConfigContext,
-	packageJsonScriptsOverrides?: PackageJsonScriptsOverrides
+	packageJsonScriptsOverrides?: PackageJsonScriptsOverrides,
+	frameworkVersionUpgradeDescription?: string
 ): Promise<AutoConfigSummary> {
 	const { logger } = context;
 	logger.log("");
@@ -411,6 +447,12 @@ export async function buildOperationsSummary(
 		logger.log("");
 	}
 
+	if (frameworkVersionUpgradeDescription) {
+		summary.frameworkVersionUpgrade = frameworkVersionUpgradeDescription;
+		logger.log(`⬆️  ${summary.frameworkVersionUpgrade}`);
+		logger.log("");
+	}
+
 	if (
 		autoConfigDetails.framework &&
 		!(autoConfigDetails.framework instanceof Static) &&

packages/autoconfig/src/types.ts

@@ -72,6 +72,7 @@ export type AutoConfigSummary = {
 	wranglerInstall: boolean;
 	wranglerConfig?: RawConfig;
 	frameworkConfiguration?: string;
+	frameworkVersionUpgrade?: string;
 	outputDir: string;
 	frameworkId?: string;
 	buildCommand?: string;