Unverified Commit c57fe256 authored by Ben Gubler's avatar Ben Gubler Committed by GitHub

feat: add a codemod to migrate from the deprecated "next lint" command (#82685)

## Add codemod to migrate from `next lint` to ESLint CLI

This PR introduces a new codemod `next-lint-to-eslint-cli` that helps
users migrate away from the deprecated `next lint` command to using
ESLint directly, in preparation for Next.js 16 where `next lint` will be
removed.

### What it does

The codemod automates the migration process by:

1. **Updating package.json scripts** - Replaces all `next lint` commands
with `eslint` equivalents
- Maps Next.js-specific flags (`--strict` → `--max-warnings 0`,
`--dir`/`--file` → paths)
   - Preserves other ESLint-compatible flags
- Handles complex scripts with pipes, redirects, and multiple commands

2. **Managing ESLint configuration**
   - Creates a new flat config (`eslint.config.mjs`) if none exists
   - Updates existing flat configs to include Next.js rules
   - Provides guidance for legacy configs that need manual migration

3. **Installing dependencies automatically**
- Adds required packages: `eslint`, `eslint-config-next`,
`@eslint/eslintrc`
   - Detects and uses the project's package manager (npm/yarn/pnpm/bun)
   - Falls back to manual instructions if installation fails

### Usage

```bash
npx @next/codemod@latest next-lint-to-eslint-cli .
```

### Example transformations

```json
// Before
{
  "scripts": {
    "lint": "next lint",
    "lint:fix": "next lint --fix",
    "lint:strict": "next lint --strict --dir src"
  }
}

// After
{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint --fix .",
    "lint:strict": "eslint --max-warnings 0 src"
  }
}
```

### Why this change?

- `next lint` is being deprecated and will be removed in Next.js 16
- ESLint v9+ flat config is becoming the standard
- Direct ESLint usage provides more flexibility and better ecosystem
compatibility
- Reduces Next.js maintenance burden of wrapping ESLint functionality

The codemod ensures a smooth transition path for existing Next.js
projects while following ESLint best practices.
parent ad48b8f4
...@@ -24,6 +24,73 @@ Replacing `<transform>` and `<path>` with appropriate values. ...@@ -24,6 +24,73 @@ Replacing `<transform>` and `<path>` with appropriate values.
## Codemods ## Codemods
### 16.0
#### Migrate from `next lint` to ESLint CLI
##### `next-lint-to-eslint-cli`
```bash filename="Terminal"
npx @next/codemod@canary next-lint-to-eslint-cli .
```
This codemod migrates projects from using `next lint` to using the ESLint CLI with your local ESLint config. It:
- Creates an `eslint.config.mjs` file with Next.js recommended configurations
- Updates `package.json` scripts to use `eslint .` instead of `next lint`
- Adds necessary ESLint dependencies to `package.json`
- Preserves existing ESLint configurations when found
For example:
```json filename="package.json"
{
"scripts": {
"lint": "next lint"
}
}
```
Becomes:
```json filename="package.json"
{
"scripts": {
"lint": "eslint ."
}
}
```
And creates:
```js filename="eslint.config.mjs"
import { dirname } from 'path'
import { fileURLToPath } from 'url'
import { FlatCompat } from '@eslint/eslintrc'
const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
const compat = new FlatCompat({
baseDirectory: __dirname,
})
const eslintConfig = [
...compat.extends('next/core-web-vitals', 'next/typescript'),
{
ignores: [
'node_modules/**',
'.next/**',
'out/**',
'build/**',
'next-env.d.ts',
],
},
]
export default eslintConfig
```
### 15.0 ### 15.0
#### Transform App Router Route Segment Config `runtime` value from `experimental-edge` to `edge` #### Transform App Router Route Segment Config `runtime` value from `experimental-edge` to `edge`
......
...@@ -113,6 +113,11 @@ export async function runTransform( ...@@ -113,6 +113,11 @@ export async function runTransform(
return require(transformerPath).default(filesExpanded, options) return require(transformerPath).default(filesExpanded, options)
} }
if (transformer === 'next-lint-to-eslint-cli') {
// next-lint-to-eslint-cli transform doesn't use jscodeshift directly
return require(transformerPath).default(filesExpanded, options)
}
let args = [] let args = []
const { dry, print, runInBand, jscodeshift, verbose } = options const { dry, print, runInBand, jscodeshift, verbose } = options
......
...@@ -31,6 +31,8 @@ export function getPkgManager(baseDir: string): PackageManager { ...@@ -31,6 +31,8 @@ export function getPkgManager(baseDir: string): PackageManager {
return 'npm' return 'npm'
} }
} }
// No lock file found, default to npm
return 'npm'
} catch { } catch {
return 'npm' return 'npm'
} }
......
...@@ -121,4 +121,9 @@ export const TRANSFORMER_INQUIRER_CHOICES = [ ...@@ -121,4 +121,9 @@ export const TRANSFORMER_INQUIRER_CHOICES = [
value: 'next-experimental-turbo-to-turbopack', value: 'next-experimental-turbo-to-turbopack',
version: '10.0.0', version: '10.0.0',
}, },
{
title: 'Migrate from `next lint` to the ESLint CLI',
value: 'next-lint-to-eslint-cli',
version: '16.0.0',
},
] ]
{
"name": "my-app",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint"
},
"dependencies": {
"react": "^18.3.0",
"react-dom": "^18.3.0",
"next": "15.0.0"
},
"devDependencies": {
"typescript": "^5",
"@types/node": "^20",
"@types/react": "^19",
"@types/react-dom": "^19"
}
}
\ No newline at end of file
{
"name": "my-app",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint ."
},
"dependencies": {
"react": "^18.3.0",
"react-dom": "^18.3.0",
"next": "15.0.0"
},
"devDependencies": {
"typescript": "^5",
"@types/node": "^20",
"@types/react": "^19",
"@types/react-dom": "^19",
"eslint": "^9",
"eslint-config-next": "15.0.0",
"@eslint/eslintrc": "^3"
}
}
\ No newline at end of file
module.exports = [
{
rules: {
"quotes": ["error", "double"],
"indent": ["error", 2]
}
}
]
\ No newline at end of file
{
"name": "complex-scripts-app",
"version": "1.0.0",
"scripts": {
"lint": "next lint --fix --dir src --dir pages",
"lint:strict": "next lint --strict",
"lint:ci": "next lint --quiet --output-file lint-results.json",
"precommit": "next lint --fix && npm test",
"test": "jest && next lint",
"complex": "npm run build && next lint --dir . --ext .js,.jsx,.ts,.tsx 2>/dev/null",
"pipe": "next lint | tee lint.log",
"redirect": "next lint > output.txt 2>&1",
"multi": "next lint; next build; next lint --fix"
},
"dependencies": {
"next": "15.0.0"
}
}
\ No newline at end of file
{
"name": "complex-scripts-app",
"version": "1.0.0",
"scripts": {
"lint": "eslint --fix src pages",
"lint:strict": "eslint --max-warnings 0 .",
"lint:ci": "eslint --quiet --output-file lint-results.json .",
"precommit": "eslint --fix . && npm test",
"test": "jest && eslint .",
"complex": "npm run build && eslint . 2>/dev/null",
"pipe": "eslint . | tee lint.log",
"redirect": "eslint . > output.txt 2>&1",
"multi": "eslint .; next build; eslint --fix ."
},
"dependencies": {
"next": "15.0.0"
},
"devDependencies": {
"eslint": "^9",
"eslint-config-next": "15.0.0",
"@eslint/eslintrc": "^3"
}
}
\ No newline at end of file
{
"name": "my-app",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint"
},
"dependencies": {
"react": "^18.3.0",
"react-dom": "^18.3.0",
"next": "15.0.0"
},
"devDependencies": {
"eslint": "^8.0.0",
"eslint-config-next": "15.0.0"
}
}
\ No newline at end of file
{
"name": "my-app",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint ."
},
"dependencies": {
"react": "^18.3.0",
"react-dom": "^18.3.0",
"next": "15.0.0"
},
"devDependencies": {
"eslint": "^8.0.0",
"eslint-config-next": "15.0.0",
"@eslint/eslintrc": "^3"
}
}
\ No newline at end of file
export default [
{
rules: {
"no-console": "warn",
"semi": ["error", "always"]
}
},
{
files: ["**/*.test.js"],
rules: {
"no-console": "off"
}
}
]
\ No newline at end of file
{
"name": "app-with-flat-config",
"version": "1.0.0",
"scripts": {
"lint": "next lint",
"lint:fix": "next lint --fix"
},
"dependencies": {
"next": "15.0.0"
}
}
\ No newline at end of file
{
"name": "app-with-flat-config",
"version": "1.0.0",
"scripts": {
"lint": "eslint .",
"lint:fix": "eslint --fix ."
},
"dependencies": {
"next": "15.0.0"
},
"devDependencies": {
"eslint": "^9",
"eslint-config-next": "15.0.0",
"@eslint/eslintrc": "^3"
}
}
\ No newline at end of file
export default [
{
ignores: ["dist/**", "coverage/**"]
},
{
rules: {
"no-unused-vars": "warn"
}
}
]
\ No newline at end of file
{
"name": "app-without-scripts",
"version": "1.0.0",
"dependencies": {
"next": "15.0.0"
}
}
\ No newline at end of file
{
"name": "app-without-scripts",
"version": "1.0.0",
"scripts": {},
"dependencies": {
"next": "15.0.0"
},
"devDependencies": {
"eslint": "^9",
"eslint-config-next": "15.0.0",
"@eslint/eslintrc": "^3"
}
}
\ No newline at end of file
This diff is collapsed.
...@@ -70,9 +70,9 @@ const nextLint = async (options: NextLintOptions, directory?: string) => { ...@@ -70,9 +70,9 @@ const nextLint = async (options: NextLintOptions, directory?: string) => {
'For new projects, use ' + 'For new projects, use ' +
bold('create-next-app') + bold('create-next-app') +
' to choose your preferred linter.\n' + ' to choose your preferred linter.\n' +
'For existing projects, migrate to explicit ESLint configuration and update your package.json scripts to use ' + 'For existing projects, migrate to the ESLint CLI:\n' +
bold('"eslint"') + bold('npx @next/codemod@canary next-lint-to-eslint-cli .') +
' instead.\n' '\n'
) )
const baseDir = getProjectDir(directory) const baseDir = getProjectDir(directory)
......
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