What is the documentation issue?

https://nextjs.org/docs/app/api-reference/config/eslint could use somewhat of a re-write, as there are multiple ambiguities on the page and has some outdated information.

Is there any context that might help us understand?

The page starts with:

Next.js provides an ESLint plugin, @next/eslint-plugin-next, already bundled within the base configuration that makes it possible to catch common issues and problems in a Next.js application.

Then it goes on to immediately show how to install eslint-config-next. This creates an immediate dissonance for readers, as one expects it to talk more about "plugins" instead of the way it is written. This can certainly be improved with a re-write. The easiest way would be to instead start with a short text only about the config, then show how to install it (as already done) and then explain it contains the @next/eslint-plugin-next, as well as the other plugins (react etc.). And change the title of the doc to just "ESLint setup".

1. This part reads strange:

Recommended rule-sets from the following ESLint plugins are all used within eslint-config-next: ... The full set of rules is as follows:

The first sentence explains it uses recommended rules from some plugins, and then says "the full set of rules". That can misinterpreted, as the "full set" includes the rules for eslint-plugin-react, eslint-plugin-react-hooks etc. This can be phrased better.

1. https://nextjs.org/docs/app/api-reference/config/eslint#migrating-existing-config is quite confusing. It says:

we recommend extending from this plugin directly instead of including eslint-config-next unless a few conditions are met.

then goes to say:

Then we recommend either removing these settings if you prefer how these properties have been configured within eslint-config-next

It is a garden-path sentence that ends in something else than what one expects. Also changing "this plugin" to "@next/eslint-plugin-next" would help readers.

1. https://nextjs.org/docs/app/api-reference/config/eslint#migrating-existing-config also shows the non-flat config way to configure in the module.exports example and should be updated.

2. https://nextjs.org/docs/app/api-reference/config/eslint#additional-configurations is confusing and worded the same as the previous section "Recommended plugin ruleset". Look at the start of the sentences:

If you already have ESLint configured in your application, we recommend extending from this plugin directly instead of including eslint-config-next unless a few conditions are met.

compared to:

If you already use a separate ESLint configuration and want to include eslint-config-next, ensure that it is extended last after other configurations. For example:

1. There is a inconsistency here:

If you already use a separate ESLint configuration and want to include eslint-config-next, ensure that it is extended last after other configurations. For example:

Then it goes to show how to use @next/eslint-plugin-next, even though the text talked about eslint-config-next.

1. It is in general now recommened to use extends together with files and it is possible that should be shown instead, see https://github.com/eslint/eslint/issues/20075 and https://github.com/eslint/eslint/issues/20046. Though using ... could be fine if that should be kept for ease-of-use.

This is important in https://nextjs.org/docs/app/api-reference/config/eslint#additional-configurations since in https://github.com/vercel/next.js/blob/canary/packages/eslint-plugin-next/src/index.ts there is no files property exported. The reason is ESLint now supports other languages than just JavaScript, e.g. JSON, in a new modern way in ESLint Flat Configs. Example how it should/can look:

import { defineConfig, globalIgnores } from 'eslint/config'
import { configs as nextConfig } from '@next/eslint-plugin-next';
 
const eslintConfig = defineConfig([
  // List of ignore patterns.
  globalIgnores([]),
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    extends: [nextConfig['core-web-vitals']],
  },
])
 
export default eslintConfig

Overall the entire documentation can be improved as it is very scattered, and to be honest, a bit confusing.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/api-reference/config/eslint