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
not be checked and continue the upgrade. Stop before changing files only if
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
Complete this checklist after updating dependencies and for each Future Defaults
......
......@@ -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.
- `--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.
For example:
......@@ -61,6 +63,7 @@ npx @next/codemod upgrade canary --yes
> **Good to know**:
>
> - 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.
> - 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) {
}
```
## 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
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
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
After applying the changes relevant to your app, review these action items before
......
......@@ -75,6 +75,16 @@ program
'Skip optional feature-adoption codemods while applying version migrations.',
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) => {
try {
await runUpgrade(revision, options)
......
......@@ -154,7 +154,10 @@ export async function runTransform(
const execaChildProcess = execa(jscodeshiftExecutable, args, {
// include ANSI color codes
// 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"
......
......@@ -113,7 +113,13 @@ function resolveSemanticRevision(
export async function runUpgrade(
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> {
const { verbose } = options
const nonInteractive = options.yes === true || !process.stdin.isTTY
......@@ -223,6 +229,7 @@ export async function runUpgrade(
// x-ref(release): https://github.com/vercel/next.js/releases/tag/v14.3.0-canary.45
compareVersions(targetNextVersion, '14.3.0-canary.45') >= 0 &&
installedReactVersion.startsWith('18') &&
!options.skipReactUpgrade &&
// Pure App Router always uses React 19
// 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.
......@@ -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`
// 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.
const targetReactVersion = shouldStayOnReact18
? '18.3.1'
: await loadHighestNPMVersionMatching(
`react@${targetNextPackageJson.peerDependencies['react']}`
)
const targetReactVersion = options.skipReactUpgrade
? installedReactVersion
: shouldStayOnReact18
? '18.3.1'
: await loadHighestNPMVersionMatching(
`react@${targetNextPackageJson.peerDependencies['react']}`
)
if (
compareVersions(targetNextVersion, '15.0.0-canary') >= 0 &&
......@@ -282,6 +291,7 @@ export async function runUpgrade(
let execCommand = 'npx --yes'
// The following React codemods are for React 19
if (
!options.skipReactUpgrade &&
!shouldStayOnReact18 &&
compareVersions(targetReactVersion, '19.0.0-0') >= 0 &&
compareVersions(installedReactVersion, '19.0.0-0') < 0
......@@ -306,11 +316,27 @@ export async function runUpgrade(
const versionMapping: Record<string, { version: string; required: boolean }> =
{
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-dom': { version: targetReactVersion, required: true },
'react-is': { version: targetReactVersion, required: false },
}
})
}
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] = {
version: targetNextVersion,
required: false,
......@@ -318,9 +344,10 @@ export async function runUpgrade(
}
if (
targetReactVersion.startsWith('19.0.0-canary') ||
targetReactVersion.startsWith('19.0.0-beta') ||
targetReactVersion.startsWith('19.0.0-rc')
!options.skipReactUpgrade &&
(targetReactVersion.startsWith('19.0.0-canary') ||
targetReactVersion.startsWith('19.0.0-beta') ||
targetReactVersion.startsWith('19.0.0-rc'))
) {
const [targetReactTypesVersion, targetReactDOMTypesVersion] =
await Promise.all([
......@@ -339,7 +366,7 @@ export async function runUpgrade(
required: false,
}
}
} else {
} else if (!options.skipReactUpgrade) {
const [targetReactTypesVersion, targetReactDOMTypesVersion] =
await Promise.all([
loadHighestNPMVersionMatching(
......@@ -374,7 +401,11 @@ export async function runUpgrade(
// Only act when the project is actually using `eslint-config-next` — we
// don't want to silently upgrade eslint majors for projects that use
// eslint for unrelated reasons.
if (allDependencies['eslint'] && allDependencies['eslint-config-next']) {
if (
!options.skipEslintUpgrade &&
allDependencies['eslint'] &&
allDependencies['eslint-config-next']
) {
try {
const eslintConfigNextPeerDepsJSON = execSync(
`npm --silent view "eslint-config-next@${targetNextVersion}" peerDependencies --json`,
......@@ -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.
const overrides: Record<string, string> = {}
if (allDependencies['@types/react']) {
if (!options.skipReactUpgrade && allDependencies['@types/react']) {
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
}
......@@ -453,7 +484,17 @@ export async function runUpgrade(
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, {
force: true,
verbose,
......@@ -495,7 +536,7 @@ export async function runUpgrade(
})
}
console.log() // new line
if (codemods.length > 0) {
if (selectedCodemods.length > 0) {
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