feat: update linting in Next.js

Author: bgub

docs/01-app/03-api-reference/06-cli/create-next-app.mdx

@@ -21,11 +21,13 @@ The following options are available:
 | --------------------------------------- | --------------------------------------------------------------- |
 | `-h` or `--help`                        | Show all available options                                      |
 | `-v` or `--version`                     | Output the version number                                       |
-| `--no-*`                                | Negate default options. E.g. `--no-eslint`                      |
+| `--no-*`                                | Negate default options. E.g. `--no-ts`                          |
 | `--ts` or `--typescript`                | Initialize as a TypeScript project (default)                    |
 | `--js` or `--javascript`                | Initialize as a JavaScript project                              |
 | `--tailwind`                            | Initialize with Tailwind CSS config (default)                   |
 | `--eslint`                              | Initialize with ESLint config                                   |
+| `--biome`                               | Initialize with Biome config                                    |
+| `--no-linter`                           | Skip linter configuration                                       |
 | `--app`                                 | Initialize as an App Router project                             |
 | `--api`                                 | Initialize a project with only route handlers                   |
 | `--src-dir`                             | Initialize inside a `src/` directory                            |
@@ -58,14 +60,24 @@ You will then be asked the following prompts:
 ```txt filename="Terminal"
 What is your project named?  my-app
 Would you like to use TypeScript?  No / Yes
-Would you like to use ESLint?  No / Yes
+Which linter would you like to use?  ESLint / Biome / None
 Would you like to use Tailwind CSS?  No / Yes
 Would you like your code inside a `src/` directory?  No / Yes
 Would you like to use App Router? (recommended)  No / Yes
 Would you like to use Turbopack? (recommended)  No / Yes
 Would you like to customize the import alias (`@/*` by default)?  No / Yes
 ```
 
+### Linter Options
+
+**ESLint**: The traditional and most popular JavaScript linter. Includes Next.js-specific rules from `eslint-plugin-next`.
+
+**Biome**: A fast, modern linter and formatter that combines the functionality of ESLint and Prettier. Includes built-in Next.js and React domain support for optimal performance.
+
+**None**: Skip linter configuration entirely. You can always add a linter later.
+
+> **Note**: `next lint` command will be deprecated in Next.js 16. New projects should use the chosen linter directly (e.g., `biome check` or `eslint`).
+
 Once you've answered the prompts, a new project will be created with your chosen configuration.
 
 ### With an official Next.js example

packages/create-next-app/create-app.ts

@@ -31,6 +31,7 @@ export async function createApp({
   typescript,
   tailwind,
   eslint,
+  biome,
   app,
   srcDir,
   importAlias,
@@ -48,6 +49,7 @@ export async function createApp({
   typescript: boolean
   tailwind: boolean
   eslint: boolean
+  biome: boolean
   app: boolean
   srcDir: boolean
   importAlias: string
@@ -235,6 +237,7 @@ export async function createApp({
       isOnline,
       tailwind,
       eslint,
+      biome,
       srcDir,
       importAlias,
       skipInstall,

packages/create-next-app/index.ts

@@ -50,6 +50,7 @@ const program = new Command(packageJson.name)
   .option('--js, --javascript', 'Initialize as a JavaScript project.')
   .option('--tailwind', 'Initialize with Tailwind CSS config. (default)')
   .option('--eslint', 'Initialize with ESLint config.')
+  .option('--biome', 'Initialize with Biome config.')
   .option('--app', 'Initialize as an App Router project.')
   .option('--src-dir', "Initialize inside a 'src/' directory.")
   .option('--turbopack', 'Enable Turbopack by default for development.')
@@ -229,6 +230,7 @@ async function run(): Promise<void> {
     const defaults: typeof preferences = {
       typescript: true,
       eslint: false,
+      linter: 'none',
       tailwind: true,
       app: true,
       srcDir: false,
@@ -277,23 +279,63 @@ async function run(): Promise<void> {
       }
     }
 
-    if (!opts.eslint && !args.includes('--no-eslint') && !opts.api) {
+    // Determine linter choice if not specified via CLI flags
+    // Support both --no-linter (new) and --no-eslint (legacy) for backward compatibility
+    const noLinter =
+      args.includes('--no-linter') || args.includes('--no-eslint')
+
+    if (!opts.eslint && !opts.biome && !noLinter && !opts.api) {
       if (skipPrompt) {
-        opts.eslint = getPrefOrDefault('eslint')
+        const preferredLinter = getPrefOrDefault('linter')
+        opts.eslint = preferredLinter === 'eslint'
+        opts.biome = preferredLinter === 'biome'
+        // No need to set noLinter flag since we check args at runtime
       } else {
-        const styledEslint = blue('ESLint')
-        const { eslint } = await prompts({
+        const { linter } = await prompts({
           onState: onPromptState,
-          type: 'toggle',
-          name: 'eslint',
-          message: `Would you like to use ${styledEslint}?`,
-          initial: getPrefOrDefault('eslint'),
-          active: 'Yes',
-          inactive: 'No',
+          type: 'select',
+          name: 'linter',
+          message: 'Which linter would you like to use?',
+          choices: [
+            {
+              title: 'ESLint',
+              value: 'eslint',
+              description: 'More comprehensive lint rules',
+            },
+            {
+              title: 'Biome',
+              value: 'biome',
+              description: 'Fast formatter and linter (fewer rules)',
+            },
+            {
+              title: 'None',
+              value: 'none',
+              description: 'Skip linter configuration',
+            },
+          ],
+          initial: 0,
         })
-        opts.eslint = Boolean(eslint)
-        preferences.eslint = Boolean(eslint)
+
+        opts.eslint = linter === 'eslint'
+        opts.biome = linter === 'biome'
+        preferences.linter = linter
+
+        // Keep backwards compatibility with old eslint preference
+        preferences.eslint = linter === 'eslint'
       }
+    } else if (opts.eslint) {
+      opts.biome = false
+      preferences.linter = 'eslint'
+      preferences.eslint = true
+    } else if (opts.biome) {
+      opts.eslint = false
+      preferences.linter = 'biome'
+      preferences.eslint = false
+    } else if (noLinter) {
+      opts.eslint = false
+      opts.biome = false
+      preferences.linter = 'none'
+      preferences.eslint = false
     }
 
     if (!opts.tailwind && !args.includes('--no-tailwind') && !opts.api) {
@@ -426,6 +468,7 @@ async function run(): Promise<void> {
       typescript: opts.typescript,
       tailwind: opts.tailwind,
       eslint: opts.eslint,
+      biome: opts.biome,
       app: opts.app,
       srcDir: opts.srcDir,
       importAlias: opts.importAlias,
@@ -459,6 +502,7 @@ async function run(): Promise<void> {
       packageManager,
       typescript: opts.typescript,
       eslint: opts.eslint,
+      biome: opts.biome,
       tailwind: opts.tailwind,
       app: opts.app,
       srcDir: opts.srcDir,

packages/create-next-app/templates/app-api/js/biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**", "!node_modules", "!.next", "!dist", "!build"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    },
+    "domains": {
+      "next": "recommended",
+      "react": "recommended"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

packages/create-next-app/templates/app-api/ts/biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**", "!node_modules", "!.next", "!dist", "!build"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    },
+    "domains": {
+      "next": "recommended",
+      "react": "recommended"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

packages/create-next-app/templates/app-empty/js/biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**", "!node_modules", "!.next", "!dist", "!build"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    },
+    "domains": {
+      "next": "recommended",
+      "react": "recommended"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

packages/create-next-app/templates/app-empty/js/eslint.config.mjs

@@ -9,6 +9,17 @@ const compat = new FlatCompat({
   baseDirectory: __dirname,
 });
 
-const eslintConfig = [...compat.extends("next/core-web-vitals")];
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals"),
+  {
+    ignores: [
+      "node_modules/**",
+      ".next/**",
+      "out/**",
+      "build/**",
+      "next-env.d.ts",
+    ],
+  },
+];
 
 export default eslintConfig;

packages/create-next-app/templates/app-empty/ts/biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**", "!node_modules", "!.next", "!dist", "!build"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    },
+    "domains": {
+      "next": "recommended",
+      "react": "recommended"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

packages/create-next-app/templates/app-empty/ts/eslint.config.mjs

@@ -11,6 +11,15 @@ const compat = new FlatCompat({
 
 const eslintConfig = [
   ...compat.extends("next/core-web-vitals", "next/typescript"),
+  {
+    ignores: [
+      "node_modules/**",
+      ".next/**",
+      "out/**",
+      "build/**",
+      "next-env.d.ts",
+    ],
+  },
 ];
 
 export default eslintConfig;

packages/create-next-app/templates/app-tw-empty/js/biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**", "!node_modules", "!.next", "!dist", "!build"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    },
+    "domains": {
+      "next": "recommended",
+      "react": "recommended"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}