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.

Author: bgub

docs/01-app/02-guides/upgrading/codemods.mdx

@@ -24,6 +24,73 @@ Replacing `<transform>` and `<path>` with appropriate values.
 
 ## 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
 
 #### Transform App Router Route Segment Config `runtime` value from `experimental-edge` to `edge`

packages/next-codemod/bin/transform.ts

@@ -113,6 +113,11 @@ export async function runTransform(
     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 = []
 
   const { dry, print, runInBand, jscodeshift, verbose } = options

packages/next-codemod/lib/handle-package.ts

@@ -31,6 +31,8 @@ export function getPkgManager(baseDir: string): PackageManager {
           return 'npm'
       }
     }
+    // No lock file found, default to npm
+    return 'npm'
   } catch {
     return 'npm'
   }

packages/next-codemod/lib/utils.ts

@@ -121,4 +121,9 @@ export const TRANSFORMER_INQUIRER_CHOICES = [
     value: 'next-experimental-turbo-to-turbopack',
     version: '10.0.0',
   },
+  {
+    title: 'Migrate from `next lint` to the ESLint CLI',
+    value: 'next-lint-to-eslint-cli',
+    version: '16.0.0',
+  },
 ]

packages/next-codemod/transforms/__testfixtures__/next-lint-to-eslint-cli/basic.input.json

@@ -0,0 +1,22 @@
+{
+  "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"
+  }
+}

packages/next-codemod/transforms/__testfixtures__/next-lint-to-eslint-cli/basic.output.json

@@ -0,0 +1,25 @@
+{
+  "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"
+  }
+}

packages/next-codemod/transforms/__testfixtures__/next-lint-to-eslint-cli/cjs-flat-config.eslint.cjs

@@ -0,0 +1,8 @@
+module.exports = [
+  {
+    rules: {
+      "quotes": ["error", "double"],
+      "indent": ["error", 2]
+    }
+  }
+]

packages/next-codemod/transforms/__testfixtures__/next-lint-to-eslint-cli/complex-scripts.input.json

@@ -0,0 +1,18 @@
+{
+  "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"
+  }
+}

packages/next-codemod/transforms/__testfixtures__/next-lint-to-eslint-cli/complex-scripts.output.json

@@ -0,0 +1,23 @@
+{
+  "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"
+  }
+}

packages/next-codemod/transforms/__testfixtures__/next-lint-to-eslint-cli/existing-eslint.input.json

@@ -0,0 +1,20 @@
+{
+  "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"
+  }
+}