Skip to content
47 changes: 22 additions & 25 deletions docs/01-app/01-getting-started/01-installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ On installation, you'll see 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
Expand Down Expand Up @@ -104,7 +104,8 @@ Then, add the following scripts to your `package.json` file:
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint"
"lint": "eslint",
"lint:fix": "eslint --fix"
}
}
```
Expand Down Expand Up @@ -309,45 +310,41 @@ You can enable the plugin in VS Code by:

See the [TypeScript reference](/docs/app/api-reference/config/next-config-js/typescript) page for more information.

## Set up ESLint
## Set up linting

Next.js comes with built-in ESLint. It automatically installs the necessary packages and configures the proper settings when you create a new project with `create-next-app`.
Next.js supports linting with either ESLint or Biome. Choose a linter and run it directly via `package.json` scripts.

To manually add ESLint to an existing project, add `next lint` as a script to `package.json`:
- Use **ESLint** (comprehensive rules):

```json filename="package.json"
{
"scripts": {
"lint": "next lint"
"lint": "eslint",
"lint:fix": "eslint --fix"
}
}
```

Then, run `npm run lint` and you will be guided through the installation and configuration process.
- Or use **Biome** (fast linter + formatter):

```bash filename="Terminal"
npm run lint
```json filename="package.json"
{
"scripts": {
"lint": "biome check",
"format": "biome format --write"
}
}
```

You'll see a prompt like this:
If your project previously used `next lint`, migrate your scripts to the ESLint CLI with the codemod:

> ? How would you like to configure ESLint?
>
> ❯ Strict (recommended)
> Base
> Cancel

- **Strict**: Includes Next.js' base ESLint configuration along with a stricter Core Web Vitals rule-set. This is the recommended configuration for developers setting up ESLint for the first time.
- **Base**: Includes Next.js' base ESLint configuration.
- **Cancel**: Skip configuration. Select this option if you plan on setting up your own custom ESLint configuration.

If `Strict` or `Base` are selected, Next.js will automatically install `eslint` and `eslint-config-next` as dependencies in your application and create a configuration file in the root of your project.

The ESLint config generated by `next lint` uses the older `.eslintrc.json` format. ESLint supports both [the legacy `.eslintrc.json` and the newer `eslint.config.mjs` format](https://eslint.org/docs/latest/use/configure/configuration-files#configuring-eslint).
```bash filename="Terminal"
npx @next/codemod@canary next-lint-to-eslint-cli .
```

You can manually replace `.eslintrc.json` with an `eslint.config.mjs` file using the setup recommended in our [ESLint API reference](/docs/app/api-reference/config/eslint#with-core-web-vitals), and installing the [`@eslint/eslintrc`](https://www.npmjs.com/package/@eslint/eslintrc) package. This more closely matches the ESLint setup used by `create-next-app`.
If you use ESLint, create an explicit config (recommended `eslint.config.mjs`). ESLint supports both [the legacy `.eslintrc.*` and the newer `eslint.config.mjs` formats](https://eslint.org/docs/latest/use/configure/configuration-files#configuring-eslint). See the [ESLint API reference](/docs/app/api-reference/config/eslint#with-core-web-vitals) for a recommended setup.

You can now run `next lint` every time you want to run ESLint to catch errors. Once ESLint has been set up, it will also automatically run during every build (`next build`). Errors will fail the build, while warnings will not.
> **Good to know**: If an ESLint config is present, `next build` will still run linting in Next.js 15, but this automatic build-time linting will be removed in Next.js 16. Control when linting runs by invoking your linter via npm scripts.

See the [ESLint Plugin](/docs/app/api-reference/config/next-config-js/eslint) page for more information.

Expand Down
10 changes: 9 additions & 1 deletion docs/01-app/03-api-reference/06-cli/next.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,15 @@ The following options are available for the `next info` command:

### `next lint` options

> **Warning**: This option is deprecated and will be removed in Next 16. A [codemod](/blog/next-15-5#next-lint-deprecation) is available to migrate to ESLint CLI.
> **Warning**: This command is deprecated and will be removed in Next.js 16.
>
> We recommend migrating to invoking ESLint directly (or using Biome). A [codemod](https://nextjs.org/blog/next-15-5#next-lint-deprecation) is available to migrate scripts to the ESLint CLI.
>
> `next lint` generates a `next-env.d.ts` file, which is often needed during type-check. To ensure `next-env.d.ts` is present run [`next typegen`](#next-typegen-options) before type-checking. `next dev` and `next build` also generate the `next-env.d.ts` file, but it is often undesirable to run these just to type-check.
>
> ```bash filename="Terminal"
> next typegen && tsc --noEmit
> ```

`next lint` runs ESLint for all files in the `pages/`, `app/`, `components/`, `lib/`, and `src/` directories. It also provides a guided setup to install any required dependencies if ESLint is not already configured in your application.

Expand Down
Loading