rsnext/docs/basic-features/eslint.md

description
Next.js provides an integrated ESLint experience by default. These conformance rules help you use Next.js in the optimal way.

ESLint

Since version 11.0.0, Next.js provides an integrated ESLint experience out of the box. Add next lint as a script to package.json:

"scripts": {
  "lint": "next lint"
}

Then run npm run lint or yarn lint:

yarn lint

If you don't already have ESLint configured in your application, you will be guided through the installation of the required packages.

yarn lint

# You'll see instructions like these:
#
# Please install eslint and eslint-config-next by running:
#
#         yarn add --dev eslint eslint-config-next
#
# ...

If no ESLint configuration is present, Next.js will create an .eslintrc file in the root of your project and automatically configure it with the base configuration:

{
  "extends": "next"
}

You can now run next lint every time you want to run ESLint to catch errors.

The default base configuration ("extends": "next") can be updated at any time and will only be included if no ESLint configuration is present.

We recommend using an appropriate integration to view warnings and errors directly in your code editor during development.

Linting During Builds

Once ESLint has been set up, it will automatically run during every build (next build). Errors will fail the build, while warnings will not.

If you do not want ESLint to run as a build step, refer to the documentation for Ignoring ESLint:

Linting Custom Directories

By default, Next.js will run ESLint for all files in the pages/, components/, and lib/ directories. However, you can specify which directories using the dirs option in the eslint config in next.config.js for production builds:

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // Only run ESLint on the 'pages' and 'utils' directories during production builds (next build)
  },
}

Similarly, the --dir flag can be used for next lint:

yarn lint --dir pages --dir utils

ESLint Plugin

Next.js provides an ESLint plugin, eslint-plugin-next, making it easier to catch common issues and problems in a Next.js application. The full set of rules is as follows:

	Rule	Description
✔️	next/google-font-display	Enforce optional or swap font-display behavior with Google Fonts
✔️	next/google-font-preconnect	Enforce preconnect usage with Google Fonts
✔️	next/link-passhref	Enforce passHref prop usage with custom Link components
✔️	next/no-css-tags	Prevent manual stylesheet tags
✔️	next/no-document-import-in-page	Disallow importing next/document outside of pages/document.js
✔️	next/no-head-import-in-document	Disallow importing next/head in pages/document.js
✔️	next/no-html-link-for-pages	Prohibit HTML anchor links to pages without a Link component
✔️	next/no-img-element	Prohibit usage of HTML <img> element
✔️	next/no-page-custom-font	Prevent page-only custom fonts
✔️	next/no-sync-scripts	Forbid synchronous scripts
✔️	next/no-title-in-document-head	Disallow using <title> with Head from next/document
✔️	next/no-unwanted-polyfillio	Prevent duplicate polyfills from Polyfill.io

• ✔: Enabled in the recommended configuration

Base Configuration

The Next.js base ESLint configuration is automatically generated when next lint is run for the first time:

{
  "extends": "next"
}

This configuration extends recommended rule sets from various ESLint plugins:

• eslint-plugin-react
• eslint-plugin-react-hooks
• eslint-plugin-next

You can see the full details of the shareable configuration in the eslint-config-next package.

Disabling Rules

If you would like to modify or disable any rules provided by the supported plugins (react, react-hooks, next), you can directly change them using the rules property in your .eslintrc:

{
  "extends": "next",
  "rules": {
    "react/no-unescaped-entities": "off",
    "@next/next/no-page-custom-font": "off",
  }
}

Note

: If you need to also include a separate, custom ESLint configuration, it is highly recommended that eslint-config-next is extended last after other configurations. For example:

{
  "extends": ["eslint:recommended", "next"]
}

The next configuration already handles setting default values for the parser, plugins and settings properties. There is no need to manually re-declare any of these properties unless you need a different configuration for your use case. If you include any other shareable configurations, you will need to make sure that these properties are not overwritten or modified.

Core Web Vitals

A stricter next/core-web-vitals rule set can also be added in .eslintrc:

{
  "extends": ["next", "next/core-web-vitals"]
}

next/core-web-vitals updates eslint-plugin-next to error on a number of rules that are warnings by default if they affect Core Web Vitals.

Both next and next/core-web-vitals entry points are automatically included for new applications built with Create Next App.

Usage with Prettier

ESLint also contains code formatting rules, which can conflict with your existing Prettier setup. We recommend including eslint-config-prettier in your ESLint config to make ESLint and Prettier work together.

{
  "extends": ["next", "prettier"]
}

Migrating Existing Config

If you already have ESLint configured in your application, we recommend extending directly from the Next.js ESLint plugin instead of the shareable configuration.

module.exports = {
  extends: [
    //...
    'plugin:@next/next/recommended',
  ],
}

This eliminates any risk of collisions that can occur due to importing the same plugin or parser across multiple configurations.