Unverified Commit a3526b8e authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

Allow skipping React and ESLint upgrades (#99468)

Stacked on #99471.

### Why?

Upgrading React or ESLint can cause peer dependency conflicts. After
restoring compatible versions, retrying the upgrade can bump them again.

### How?

Add `--skip-react-upgrade` and `--skip-eslint-upgrade` to skip the
corresponding dependency updates and codemods. The React flag also
preserves types and overrides.

Add troubleshooting checklists to the version guides and point upgrade
agents to them. Required migrations still need to be completed before
verification; if Next.js already matches the target, run the interrupted
migrations individually.
parent 7bc06f4a
...@@ -28,6 +28,11 @@ provider lookup. If a check is unavailable or fails, report which work could ...@@ -28,6 +28,11 @@ provider lookup. If a check is unavailable or fails, report which work could
not be checked and continue the upgrade. Stop before changing files only if not be checked and continue the upgrade. Stop before changing files only if
you find equivalent work. you find equivalent work.
## During the upgrade: troubleshoot failures
- [ ] Check the relevant version upgrade guides for troubleshooting sections
and follow any applicable checklists before verification or delivery.
## Verify ## Verify
Complete this checklist after updating dependencies and for each Future Defaults Complete this checklist after updating dependencies and for each Future Defaults
......
...@@ -34,6 +34,8 @@ npx @next/codemod upgrade [revision] ...@@ -34,6 +34,8 @@ npx @next/codemod upgrade [revision]
- `revision` (optional): Specify the upgrade type (`patch`, `minor`, `major`), an NPM dist tag (e.g. `latest`, `canary`, `rc`), or an exact version (e.g. `15.0.0`). Defaults to `minor` for stable versions. - `revision` (optional): Specify the upgrade type (`patch`, `minor`, `major`), an NPM dist tag (e.g. `latest`, `canary`, `rc`), or an exact version (e.g. `15.0.0`). Defaults to `minor` for stable versions.
- `--verbose`: Show more detailed output during the upgrade process. - `--verbose`: Show more detailed output during the upgrade process.
- `--skip-react-upgrade`: Preserve React dependencies, types, and overrides, and skip React codemods.
- `--skip-eslint-upgrade`: Preserve `eslint`, `eslint-config-next`, `@next/eslint-plugin-next`, and skip `next-lint-to-eslint-cli`. Complete required lint migrations manually before verification.
- `-y, --yes`: Skip every interactive prompt and accept its default (upgrade React past 18, enable Turbopack, apply all recommended codemods, run the React 19 codemods). Also auto-enabled when stdin is not a TTY (CI, an AI coding agent, or any non-interactive shell), so you usually don't need to pass it explicitly. - `-y, --yes`: Skip every interactive prompt and accept its default (upgrade React past 18, enable Turbopack, apply all recommended codemods, run the React 19 codemods). Also auto-enabled when stdin is not a TTY (CI, an AI coding agent, or any non-interactive shell), so you usually don't need to pass it explicitly.
For example: For example:
...@@ -61,6 +63,7 @@ npx @next/codemod upgrade canary --yes ...@@ -61,6 +63,7 @@ npx @next/codemod upgrade canary --yes
> **Good to know**: > **Good to know**:
> >
> - If the target version is the same as or lower than your current version, the command exits without making changes. > - If the target version is the same as or lower than your current version, the command exits without making changes.
> - The skip flags do not bypass the target's peer dependency requirements. If installation previously failed, repair the dependencies and retry the same exact target with the relevant flag. If Next.js already matches the target, run any skipped migrations individually using the guides below.
> - During the upgrade, you may be prompted to choose which Next.js codemods to apply and run React 19 codemods if upgrading React. > - During the upgrade, you may be prompted to choose which Next.js codemods to apply and run React 19 codemods if upgrading React.
> - When invoked by an AI coding agent or in CI (anywhere stdin isn't a TTY), the upgrade runs non-interactively and accepts every default. Pass `--yes` to force this behavior even from a terminal. > - When invoked by an AI coding agent or in CI (anywhere stdin isn't a TTY), the upgrade runs non-interactively and accepts every default. Pass `--yes` to force this behavior even from a terminal.
......
...@@ -626,6 +626,19 @@ export function middleware(request: NextRequest) { ...@@ -626,6 +626,19 @@ export function middleware(request: NextRequest) {
} }
``` ```
## Troubleshooting
### Installation fails after upgrading to React 19
- [ ] If another package's peer dependencies reject React 19, revert `react`, `react-dom`, their types, and `react-is` (if present) to the previous versions, provided the target Next.js version and router support them.
- [ ] Restore or remove React type overrides or resolutions added by the upgrade in `package.json` or `pnpm-workspace.yaml`.
- [ ] If installation interrupted the upgrade command, retry the same exact target with `--skip-react-upgrade` to preserve the repaired dependencies. If Next.js already matches the target, install dependencies and run any skipped codemods individually. Run the app's checks.
### Installation fails after upgrading to ESLint 9
- [ ] If another package's peer dependencies reject ESLint 9, restore the previous compatible versions of `eslint`, `eslint-config-next`, and `@next/eslint-plugin-next` (if present), along with the previous lint configuration.
- [ ] If installation interrupted the upgrade command, retry the same exact target with `--skip-eslint-upgrade` to preserve the repaired dependency. If Next.js already matches the target, install dependencies and run any skipped codemods individually. Complete any required lint migration manually, then run the app's lint checks.
## Review migration checklist ## Review migration checklist
After applying the changes relevant to your app, review these action items before After applying the changes relevant to your app, review these action items before
......
...@@ -1249,6 +1249,19 @@ For the full migration path, see [Migrating to Cache Components](/docs/app/guide ...@@ -1249,6 +1249,19 @@ For the full migration path, see [Migrating to Cache Components](/docs/app/guide
The `unstable_rootParams` function has been removed. Use [`next/root-params`](/docs/app/api-reference/functions/next-root-params) instead. The `unstable_rootParams` function has been removed. Use [`next/root-params`](/docs/app/api-reference/functions/next-root-params) instead.
## Troubleshooting
### Installation fails after upgrading to React 19
- [ ] Follow the [React recovery checklist](/docs/app/guides/upgrading/version-15#installation-fails-after-upgrading-to-react-19).
### Installation fails after upgrading ESLint
Next.js 16 removes `next lint`, but migrating to the ESLint CLI does not require upgrading ESLint. `eslint-config-next@16` requires ESLint 9; an existing compatible lint configuration can use an older version.
- [ ] If an ESLint upgrade causes peer dependency conflicts, restore the previous compatible versions of `eslint`, `eslint-config-next`, and `@next/eslint-plugin-next` (if present), along with the previous lint configuration.
- [ ] If installation interrupted the upgrade, retry the same exact target with `--skip-eslint-upgrade` to preserve the repaired lint stack and skip the lint codemod. If Next.js already matches the target, install dependencies and complete interrupted migrations individually. Replace `next lint` scripts with ESLint CLI commands compatible with the preserved configuration. Confirm installation and lint pass.
## Review migration checklist ## Review migration checklist
After applying the changes relevant to your app, review these action items before After applying the changes relevant to your app, review these action items before
......
...@@ -75,6 +75,16 @@ program ...@@ -75,6 +75,16 @@ program
'Skip optional feature-adoption codemods while applying version migrations.', 'Skip optional feature-adoption codemods while applying version migrations.',
false false
) )
.option(
'--skip-react-upgrade',
'Keep React dependencies, types, and overrides unchanged and skip React codemods.',
false
)
.option(
'--skip-eslint-upgrade',
'Keep ESLint dependencies unchanged and skip the next-lint-to-eslint-cli codemod.',
false
)
.action(async (revision, options) => { .action(async (revision, options) => {
try { try {
await runUpgrade(revision, options) await runUpgrade(revision, options)
......
...@@ -154,7 +154,10 @@ export async function runTransform( ...@@ -154,7 +154,10 @@ export async function runTransform(
const execaChildProcess = execa(jscodeshiftExecutable, args, { const execaChildProcess = execa(jscodeshiftExecutable, args, {
// include ANSI color codes // include ANSI color codes
// Note: execa merges env with existing env by default. // Note: execa merges env with existing env by default.
env: process.stdout.isTTY ? { FORCE_COLOR: 'true' } : {}, env: {
...process.env,
...(process.stdout.isTTY ? { FORCE_COLOR: 'true' } : {}),
},
}) })
// "\n" + "a\n" + "b\n" // "\n" + "a\n" + "b\n"
......
...@@ -113,7 +113,13 @@ function resolveSemanticRevision( ...@@ -113,7 +113,13 @@ function resolveSemanticRevision(
export async function runUpgrade( export async function runUpgrade(
revision: string | undefined, revision: string | undefined,
options: { verbose: boolean; yes?: boolean; skipAdoption?: boolean } options: {
verbose: boolean
yes?: boolean
skipAdoption?: boolean
skipReactUpgrade: boolean | undefined
skipEslintUpgrade: boolean | undefined
}
): Promise<void> { ): Promise<void> {
const { verbose } = options const { verbose } = options
const nonInteractive = options.yes === true || !process.stdin.isTTY const nonInteractive = options.yes === true || !process.stdin.isTTY
...@@ -223,6 +229,7 @@ export async function runUpgrade( ...@@ -223,6 +229,7 @@ export async function runUpgrade(
// x-ref(release): https://github.com/vercel/next.js/releases/tag/v14.3.0-canary.45 // x-ref(release): https://github.com/vercel/next.js/releases/tag/v14.3.0-canary.45
compareVersions(targetNextVersion, '14.3.0-canary.45') >= 0 && compareVersions(targetNextVersion, '14.3.0-canary.45') >= 0 &&
installedReactVersion.startsWith('18') && installedReactVersion.startsWith('18') &&
!options.skipReactUpgrade &&
// Pure App Router always uses React 19 // Pure App Router always uses React 19
// The mixed case is tricky to handle from a types perspective. // The mixed case is tricky to handle from a types perspective.
// We'll recommend to upgrade in the prompt but users can decide to try 18. // We'll recommend to upgrade in the prompt but users can decide to try 18.
...@@ -256,11 +263,13 @@ export async function runUpgrade( ...@@ -256,11 +263,13 @@ export async function runUpgrade(
// E.g. in peerDependencies we could have `^18.2.0 || ^19.0.0 || 20.0.0-canary` // E.g. in peerDependencies we could have `^18.2.0 || ^19.0.0 || 20.0.0-canary`
// If we'd just `npm add` that, the manifest would read the same version query. // If we'd just `npm add` that, the manifest would read the same version query.
// This is basically a `npm --save-exact react@$versionQuery` that works for every package manager. // This is basically a `npm --save-exact react@$versionQuery` that works for every package manager.
const targetReactVersion = shouldStayOnReact18 const targetReactVersion = options.skipReactUpgrade
? '18.3.1' ? installedReactVersion
: await loadHighestNPMVersionMatching( : shouldStayOnReact18
`react@${targetNextPackageJson.peerDependencies['react']}` ? '18.3.1'
) : await loadHighestNPMVersionMatching(
`react@${targetNextPackageJson.peerDependencies['react']}`
)
if ( if (
compareVersions(targetNextVersion, '15.0.0-canary') >= 0 && compareVersions(targetNextVersion, '15.0.0-canary') >= 0 &&
...@@ -282,6 +291,7 @@ export async function runUpgrade( ...@@ -282,6 +291,7 @@ export async function runUpgrade(
let execCommand = 'npx --yes' let execCommand = 'npx --yes'
// The following React codemods are for React 19 // The following React codemods are for React 19
if ( if (
!options.skipReactUpgrade &&
!shouldStayOnReact18 && !shouldStayOnReact18 &&
compareVersions(targetReactVersion, '19.0.0-0') >= 0 && compareVersions(targetReactVersion, '19.0.0-0') >= 0 &&
compareVersions(installedReactVersion, '19.0.0-0') < 0 compareVersions(installedReactVersion, '19.0.0-0') < 0
...@@ -306,11 +316,27 @@ export async function runUpgrade( ...@@ -306,11 +316,27 @@ export async function runUpgrade(
const versionMapping: Record<string, { version: string; required: boolean }> = const versionMapping: Record<string, { version: string; required: boolean }> =
{ {
next: { version: targetNextVersion, required: true }, next: { version: targetNextVersion, required: true },
}
// Recovery retries must preserve the repaired React declarations and pins.
if (!options.skipReactUpgrade) {
Object.assign(versionMapping, {
react: { version: targetReactVersion, required: true }, react: { version: targetReactVersion, required: true },
'react-dom': { version: targetReactVersion, required: true }, 'react-dom': { version: targetReactVersion, required: true },
'react-is': { version: targetReactVersion, required: false }, 'react-is': { version: targetReactVersion, required: false },
} })
}
for (const optionalNextjsPackage of optionalNextjsPackages) { for (const optionalNextjsPackage of optionalNextjsPackages) {
// Preserve the lint stack together; its newer config can require newer ESLint.
if (
options.skipEslintUpgrade &&
(optionalNextjsPackage === 'eslint-config-next' ||
optionalNextjsPackage === '@next/eslint-plugin-next')
) {
continue
}
versionMapping[optionalNextjsPackage] = { versionMapping[optionalNextjsPackage] = {
version: targetNextVersion, version: targetNextVersion,
required: false, required: false,
...@@ -318,9 +344,10 @@ export async function runUpgrade( ...@@ -318,9 +344,10 @@ export async function runUpgrade(
} }
if ( if (
targetReactVersion.startsWith('19.0.0-canary') || !options.skipReactUpgrade &&
targetReactVersion.startsWith('19.0.0-beta') || (targetReactVersion.startsWith('19.0.0-canary') ||
targetReactVersion.startsWith('19.0.0-rc') targetReactVersion.startsWith('19.0.0-beta') ||
targetReactVersion.startsWith('19.0.0-rc'))
) { ) {
const [targetReactTypesVersion, targetReactDOMTypesVersion] = const [targetReactTypesVersion, targetReactDOMTypesVersion] =
await Promise.all([ await Promise.all([
...@@ -339,7 +366,7 @@ export async function runUpgrade( ...@@ -339,7 +366,7 @@ export async function runUpgrade(
required: false, required: false,
} }
} }
} else { } else if (!options.skipReactUpgrade) {
const [targetReactTypesVersion, targetReactDOMTypesVersion] = const [targetReactTypesVersion, targetReactDOMTypesVersion] =
await Promise.all([ await Promise.all([
loadHighestNPMVersionMatching( loadHighestNPMVersionMatching(
...@@ -374,7 +401,11 @@ export async function runUpgrade( ...@@ -374,7 +401,11 @@ export async function runUpgrade(
// Only act when the project is actually using `eslint-config-next` — we // Only act when the project is actually using `eslint-config-next` — we
// don't want to silently upgrade eslint majors for projects that use // don't want to silently upgrade eslint majors for projects that use
// eslint for unrelated reasons. // eslint for unrelated reasons.
if (allDependencies['eslint'] && allDependencies['eslint-config-next']) { if (
!options.skipEslintUpgrade &&
allDependencies['eslint'] &&
allDependencies['eslint-config-next']
) {
try { try {
const eslintConfigNextPeerDepsJSON = execSync( const eslintConfigNextPeerDepsJSON = execSync(
`npm --silent view "eslint-config-next@${targetNextVersion}" peerDependencies --json`, `npm --silent view "eslint-config-next@${targetNextVersion}" peerDependencies --json`,
...@@ -414,10 +445,10 @@ export async function runUpgrade( ...@@ -414,10 +445,10 @@ export async function runUpgrade(
// we still do it out of safety due to https://github.com/microsoft/DefinitelyTyped-tools/issues/433. // we still do it out of safety due to https://github.com/microsoft/DefinitelyTyped-tools/issues/433.
const overrides: Record<string, string> = {} const overrides: Record<string, string> = {}
if (allDependencies['@types/react']) { if (!options.skipReactUpgrade && allDependencies['@types/react']) {
overrides['@types/react'] = versionMapping['@types/react'].version overrides['@types/react'] = versionMapping['@types/react'].version
} }
if (allDependencies['@types/react-dom']) { if (!options.skipReactUpgrade && allDependencies['@types/react-dom']) {
overrides['@types/react-dom'] = versionMapping['@types/react-dom'].version overrides['@types/react-dom'] = versionMapping['@types/react-dom'].version
} }
...@@ -453,7 +484,17 @@ export async function runUpgrade( ...@@ -453,7 +484,17 @@ export async function runUpgrade(
runInstallation(packageManager, { cwd }) runInstallation(packageManager, { cwd })
for (const codemod of codemods) { // Opting out skips the lint migration as well as its dependency upgrades.
const selectedCodemods = codemods.filter(
(codemod) =>
!options.skipEslintUpgrade || codemod !== 'next-lint-to-eslint-cli'
)
if (selectedCodemods.length !== codemods.length) {
console.log(
'Skipping next-lint-to-eslint-cli. Complete any required lint migration manually before verification.'
)
}
for (const codemod of selectedCodemods) {
await runTransform(codemod, cwd, { await runTransform(codemod, cwd, {
force: true, force: true,
verbose, verbose,
...@@ -495,7 +536,7 @@ export async function runUpgrade( ...@@ -495,7 +536,7 @@ export async function runUpgrade(
}) })
} }
console.log() // new line console.log() // new line
if (codemods.length > 0) { if (selectedCodemods.length > 0) {
console.log(`${pc.green('✔')} Codemods have been applied successfully.`) console.log(`${pc.green('✔')} Codemods have been applied successfully.`)
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment