Working with ESLint

There is now an integrated ESLint experience in Next.js. You can add next lint to your script in your package.json.

ESLint + Next.js Options

1. Strict: This includes the base ESLint configuration and also includes the stricter Core Web Vitals rule-set. This is the recommended configuration for developers that are setting up ESLint for the first time.

2. Base: This includes just Next.js' base ESLint configuration.

3. Cancel: Does not include ESLint configuration. This option should only be used if you are going to set up your own configuration.

When you have selected either the strict or base version, Next.js will automatically install eslint and eslint-config-next as development dependencies in your application. This will create an .eslintrc.json file in the root of your project.

ESLint Config

The default configuration is eslint-config-next and contains everything you need to have an optimal linting experience. Use next lint to set up ESLint.

ESLint Plugin

The ESLint plugin eslint-plugin-next is already bundled within the base configuration. This makes it possible to catch common issues and problems that are in a Next.js application. There are a bunch of rules.

Disabling Rules

Since this plugin has a lot of rules, it can happen that there are a few rules you might want to remove, because they are not working for you.

You can modify or disable rules that are provided by the support plug ins. These can be changed directly using the rules property in your .eslintrc.

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

Custom Settings

It is possible that you are working in a project where Next.js is not installed in your root directory. You can tell Next.js where to find the project in your .eslintrc.

{
  "extends": "next",
  "settings": 
    {
      "next": 
        {
          "rootDir": "/packages/my-app/"
        }
    }
}

Linting Custom Directories and Files

The default for Next.js is that is will run ESLint for all files in the following directories:

• pages/

• components/

• lib/

You can also specify which other directories you want to be linted by using the dirs option in the eslint config in next.config.js for production builds.

module.exports = {
  eslint: { dirs: ['pages', 'utils'], 
    // this only runs eslint on the pages and utils
  },
}

You can also use --dir and --file flags with the next lint in your terminal.

Caching

ESLint caches information of files when it processes it by default to improve performance. This is stored in .next/cache or in your defined build directory. You can also disable the caching if you need to with the flag --no-cache when using next lint in your terminal.

Using with Other Tools

Prettier

Just like Prettier, ESLint contains code formatting rules. This can give conflicts when you have an existing Prettier setup. You can include eslint-config-prettier inside of your ESLing config. This will make ESLint and Prettier work together.

You'll have to install the dependency first, this can be done with the following command in your terminal:

npm install --save-dev eslint-config-prettier
// or
yarn add --dev eslint-config-prettier

You can then add prettier to your existing ESLint config.

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

Lint-staged

If you want to use next lint together with lint-staged so it can run the linter on staged git files, there is one line you will have to add to your root of the project. The line is .lintstagedrc.js.

Then, you can specify the usage of the --file flag.

module.exports = {
  '**/*?(x)': (filenames) =>
  `next lint --fix --file ${filenames.map((file) => 
    file.split(process.cwd())[1]).join(' --file ')}`,
    }

External sources

Next.js docs about ESLint

Official ESLint website

Official Prettier website

Official Lint-staged repository