feat: add a codemod to migrate from the deprecated "next lint" command

Author: bgub

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

@@ -24,6 +24,78 @@ 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@latest next-lint-to-eslint-cli .
+```
+
+This codemod migrates projects from using `next lint` to using the ESLint CLI using 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 ."
+  },
+  "devDependencies": {
+    "eslint": "^9",
+    "eslint-config-next": "latest",
+    "@eslint/eslintrc": "^3"
+  }
+}
+```
+
+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/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/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"
+  }
+}

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

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

packages/next-codemod/transforms/__tests__/next-lint-to-eslint-cli.test.js

@@ -0,0 +1,96 @@
+/* global jest */
+jest.autoMockOff()
+const fs = require('fs')
+const path = require('path')
+const { tmpdir } = require('os')
+const transformer = require('../next-lint-to-eslint-cli').default
+
+describe('next-lint-to-eslint-cli', () => {
+  let tempDir
+
+  beforeEach(() => {
+    // Create a unique temp directory for each test
+    tempDir = fs.mkdtempSync(path.join(tmpdir(), 'codemod-test-'))
+  })
+
+  afterEach(() => {
+    // Clean up temp directory
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
+
+  test('transforms correctly using basic data', () => {
+    // Read input fixture
+    const inputPath = path.join(__dirname, '../__testfixtures__/next-lint-to-eslint-cli/basic.input.json')
+    const expectedOutputPath = path.join(__dirname, '../__testfixtures__/next-lint-to-eslint-cli/basic.output.json')
+    
+    const inputContent = fs.readFileSync(inputPath, 'utf8')
+    const expectedOutput = fs.readFileSync(expectedOutputPath, 'utf8')
+
+    // Set up test project
+    const packageJsonPath = path.join(tempDir, 'package.json')
+    const tsConfigPath = path.join(tempDir, 'tsconfig.json')
+    
+    fs.writeFileSync(packageJsonPath, inputContent)
+    fs.writeFileSync(tsConfigPath, '{}') // Create tsconfig.json to indicate TypeScript project
+
+    // Run transformer
+    const consoleSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    
+    transformer([tempDir], {})
+
+    // Check package.json was updated correctly
+    const actualPackageJson = fs.readFileSync(packageJsonPath, 'utf8')
+    expect(JSON.parse(actualPackageJson)).toEqual(JSON.parse(expectedOutput))
+
+    // Check eslint.config.mjs was created
+    const eslintConfigPath = path.join(tempDir, 'eslint.config.mjs')
+    expect(fs.existsSync(eslintConfigPath)).toBe(true)
+    
+    const eslintConfig = fs.readFileSync(eslintConfigPath, 'utf8')
+    expect(eslintConfig).toContain('next/core-web-vitals')
+    expect(eslintConfig).toContain('next/typescript')
+    expect(eslintConfig).toContain('ignores:')
+
+    consoleSpy.mockRestore()
+    consoleErrorSpy.mockRestore()
+  })
+
+  test('transforms correctly using existing-eslint data', () => {
+    // Read input fixture
+    const inputPath = path.join(__dirname, '../__testfixtures__/next-lint-to-eslint-cli/existing-eslint.input.json')
+    const expectedOutputPath = path.join(__dirname, '../__testfixtures__/next-lint-to-eslint-cli/existing-eslint.output.json')
+    
+    const inputContent = fs.readFileSync(inputPath, 'utf8')
+    const expectedOutput = fs.readFileSync(expectedOutputPath, 'utf8')
+
+    // Set up test project
+    const packageJsonPath = path.join(tempDir, 'package.json')
+    const existingEslintPath = path.join(tempDir, '.eslintrc.json')
+    
+    fs.writeFileSync(packageJsonPath, inputContent)
+    fs.writeFileSync(existingEslintPath, '{"extends": ["next"]}') // Create existing ESLint config
+
+    // Run transformer
+    const consoleSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    
+    transformer([tempDir], {})
+
+    // Check package.json was updated correctly
+    const actualPackageJson = fs.readFileSync(packageJsonPath, 'utf8')
+    expect(JSON.parse(actualPackageJson)).toEqual(JSON.parse(expectedOutput))
+
+    // Check that no new eslint.config.mjs was created (existing config should be preserved)
+    const eslintConfigPath = path.join(tempDir, 'eslint.config.mjs')
+    expect(fs.existsSync(eslintConfigPath)).toBe(false)
+
+    // Check that existing config still exists
+    expect(fs.existsSync(existingEslintPath)).toBe(true)
+
+    consoleSpy.mockRestore()
+    consoleErrorSpy.mockRestore()
+  })
+})