How to use new "flat config" approach in Eslint?

[ryancwalsh]

Summary

I have Eslint working in a TypeScript Next.js project, but I want to switch to the new "flat config" approach that Eslint offers.

(Why is that not Next.js's default?)

I created /eslint.config.js to look something like this: https://stackoverflow.com/a/74819187/470749

Part 1

How can I migrate the extends: ['next/core-web-vitals'], to the flat config, which doesn't support extends?

Part 2

Other than missing 'next/core-web-vitals', if I run eslint pages/*, I see the errors that I expect.

But my VSCode no longer shows errors.

I see "eslint.experimental.useFlatConfig": true, in my VSC settings, and I've restarted VSC, but it still doesn't work.

How can I get the flat config to run automatically in VSC?

Additional information

No response

Example

No response

[milos-sikic-nimbus-tech]

This worked for me. I haven't tested it thoroughly, but it reports that I shouldn't use the <img> component, for example. If more people could test it out and provide feedback, I might be able to tweak it further.

import nextPlugin from '@next/eslint-plugin-next';
import reactPlugin from 'eslint-plugin-react';
import hooksPlugin from 'eslint-plugin-react-hooks';

export default [
  {
    plugins: {
      react: reactPlugin,
    },
    rules: {
      ...reactPlugin.configs['jsx-runtime'].rules,
    },
    settings: {
      react: {
        version: 'detect', // You can add this if you get a warning about the React version when you lint
      },
    },
  },
  {
    plugins: {
      'react-hooks': hooksPlugin,
    },
    rules: hooksPlugin.configs.recommended.rules,
  },
  {
    plugins: {
      '@next/next': nextPlugin,
    },
    rules: {
      ...nextPlugin.configs.recommended.rules,
      ...nextPlugin.configs['core-web-vitals'].rules,
    },
  },
  {
    ignores: ['.next/*'],
  },
];

You need to install @next/eslint-plugin-next, eslint-plugin-react and eslint-plugin-react-hooks as dev dependencies.

[ryancwalsh]

Thanks for your response @milos-sikic-nimbus-tech .

I ran yarn add -D @next/eslint-plugin-next eslint-plugin-react eslint-plugin-react-hooks.

My only eslint settings in my VSC's settings.json are:

"eslint.experimental.useFlatConfig": true,
  "eslint.debug": true,
  "eslint.options": {
    "overrideConfigFile": "eslint.config.mjs"
  },
  "settingsSync.ignoredSettings": [
    "eslint.experimental.useFlatConfig"
  ],

I've tried putting the config at eslint.config.mjs and eslint.config.mjs. I've tried with and without "type": "module", in my package.json.

npx eslint and ./node_modules/.bin/eslint both give no output.

I have no .eslintignore file.

My guess is that you're not using TypeScript. Using your approach, I was able to get VSC to highlight errors in regular JS, but I never want to use JS. I always use TS and TSX now.

Here is my eslint.config.js currently:

import nextPlugin from '@next/eslint-plugin-next';
import reactPlugin from 'eslint-plugin-react';
import hooksPlugin from 'eslint-plugin-react-hooks';
import ts from '@typescript-eslint/eslint-plugin';
import tsParser from '@typescript-eslint/parser';
import functional from 'eslint-plugin-functional';
import imprt from 'eslint-plugin-import'; // 'import' is ambiguous & prettier has trouble

const myRules = {
  // https://eslint.org/docs/latest/rules/max-len
  // Temporary rule to see if eslint will work:
  'max-len': ['warn', { code: 3, ignoreComments: false, ignoreRegExpLiterals: true, ignoreStrings: true, ignoreTemplateLiterals: true }],
};

export default [
  {
    rules: myRules,
  },
  {
    plugins: {
      react: reactPlugin,
    },
    rules: {
      ...reactPlugin.configs['jsx-runtime'].rules,
    },
    settings: {
      react: {
        version: 'detect', // You can add this if you get a warning about the React version when you lint
      },
    },
  },
  {
    plugins: {
      'react-hooks': hooksPlugin,
    },
    rules: hooksPlugin.configs.recommended.rules,
  },
  {
    plugins: {
      '@next/next': nextPlugin,
    },
    rules: {
      ...nextPlugin.configs.recommended.rules,
      ...nextPlugin.configs['core-web-vitals'].rules,
    },
  },
  {
    ignores: ['.next/*'],
  },
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        ecmaFeatures: { modules: true },
        ecmaVersion: 'latest',
        project: './tsconfig.json',
      },
    },
    plugins: {
      functional,
      import: imprt,
      '@typescript-eslint': ts,
      ts,
    },
    rules: {
      ...ts.configs['eslint-recommended'].rules,
      ...ts.configs['recommended'].rules,
      ...myRules,
      'ts/return-await': 2,
    },
  },
];

./node_modules/.bin/eslint . shows warnings as I'd expect.

However, my VSC is not showing them as I type (the way it did before switching to flat config).

Thanks for any ideas.

[milos-sikic-nimbus-tech]

Hmm, it worked for me for TS and TSX files. Might be that it's missing the matcher?

We could maybe put the React and Next stuff into one object and add files: ['**/*.ts', '**/*.tsx'], to it.

Something like this:

export default [
  {
    files: ['**/*.ts', '**/*.tsx'],
    plugins: {
      react: reactPlugin,
      'react-hooks': hooksPlugin,
      '@next/next': nextPlugin,
    },
    rules: {
      ...reactPlugin.configs['jsx-runtime'].rules,
      ...hooksPlugin.configs.recommended.rules,
      ...nextPlugin.configs.recommended.rules,
      ...nextPlugin.configs['core-web-vitals'].rules,
      '@next/next/no-img-element': 'error',
    },
  },
  ... rest of your config
]

And yes, sorry, I didn't include one other plugin that we're using that's internal that might be helping. But I just took a look, and it's very similar to what you're doing, even the order in the array is the same.

Also, if you're not already, always restart the ESLint Server within VS Code when you change the config if you want to see the changes - it doesn't pick up on them all the time. Doing a restart guarantees that the newest config is loaded. Also, check out the output of the ESLint plugin (Cmd + Shift + P and type "ESLint output", you'll find the command).

Let me know if that helps!

[ryancwalsh]

Thank you so much, @milos-sikic-nimbus-tech !!

I had already seen in the terminal TypeError: Could not find the rule "canonical/filename-match-exported"., but I'd ignored it.

Seeing it again in ESLint Show Output Channel made me wonder whether VSC was aborting there and not bothering to run any more rules.

And that seems to be the case.

Once I removed /* eslint-disable canonical/filename-match-exported */ from the files that had those comments, VSC started honoring my ESLint rules (even in tsx files).

Thanks!

[milos-sikic-nimbus-tech]

For the canonical rule, you're probably missing the plugin: eslint-plugin-canonical.

Install that as a dev dependency

Import it as import canonical from eslint-plugin-canonical

And then just include it as a plugin

...
plugins: {
   canonical,
   ...
},
...

Do note that the name of the plugin is important here. In order for rules to be picked up, you need to specify a name for the plugin that's the same as the one that's used in the rules string, and comes before the / sign. This would also work:

import it as `import canonicalPlugin from eslint-plugin-canonical`

...
plugins: {
   canonical: canonicalPlugin
},
...

And according to the documentation, also this (haven't tested it):

import it as `import canonicalPlugin from eslint-plugin-canonical`

...
plugins: {
  canonicalPlugin
},
rules: {
   "canonicalPlugin/filename-match-exported": warn
}
...

Also, you're welcome! Glad it's working for you! :)

[ryancwalsh]

Thanks. Yeah, I partially got 'canonical' working like this: eslint/eslint#17228 But as I describe there, there is much more I'd love to get working.

I might switch from FlatCompat to your approach too.

[nyxb]

hey maybe you can help me too. I can activate the rules only if I enter them individually the standard rules have no effect.

import type { ConfigItem, OptionsHasTypeScript, OptionsOverrides, OptionsStylistic } from '../types'

import { GLOB_NEXT } from '../globs'
import { parserTs, pluginNext, pluginReact, pluginReactHooks } from '../plugins'

export function next(
   options: OptionsHasTypeScript & OptionsOverrides & OptionsStylistic = {},
): ConfigItem[] {
   const {
      overrides = {},
      stylistic = true,
   } = options

   return [
      {
         name: 'nyxb:next:setup',
         plugins: {
            'next': pluginNext,
            'react': pluginReact,
            'react-hooks': pluginReactHooks,
         },
      },
      {
         files: [GLOB_NEXT],
         languageOptions: {
            parser: options.typescript ? parserTs as any : null,
            parserOptions: {
               ecmaFeatures: {
                  jsx: true,
               },
               sourceType: 'module',
            },
         },
         name: 'nyxb:next:rules',
         rules: {
            ...pluginReact.configs['jsx-runtime'].rules as any,
            ...pluginReactHooks.configs.recommended.rules as any,
            ...pluginNext.configs.recommended.rules as any,
            ...pluginNext.configs['core-web-vitals'].rules as any,
            'next/google-font-display': 'error',
            ...stylistic
               ? {
                  }
               : {},

            ...overrides,
         },
      },
   ]
}

in the screenshots you can see that only conditional rules are activated and in the next rules actually only the one that I have activated individually.

React:

React Hooks:

Next:

all other are off:

the packages are all on the latest version

[bestickley]

@ryancwalsh, did you consider using FlatCompat from @eslint/eslintrc like below?

import path from "node:path";
import { fileURLToPath } from "url";
import { FlatCompat } from "@eslint/eslintrc";
import { defineFlatConfig } from "eslint-define-config";
import ts from "@typescript-eslint/eslint-plugin";
import tsParser from "@typescript-eslint/parser";
import js from "@eslint/js";

const baseDirectory = path.dirname(fileURLToPath(import.meta.url));

const compat = new FlatCompat({
  baseDirectory,
  resolvePluginsRelativeTo: baseDirectory,
});

export default defineFlatConfig([
{
    files: ["**/*.{ts,tsx}"],
    plugins: {
      "@typescript-eslint": ts,
    },
    languageOptions: {
      parser: tsParser,
    },
    rules: {
      ...js.configs.recommended.rules,
      ...ts.configs.recommended.rules,
    },
  },
  compat.config({
      overrides: [
        { files: "ui/**/*.{ts,tsx}", extends: "next/core-web-vitals" },
      ],
    })
]);

I'm having issues getting this to work, but theoretically I think this is the ideal solution.

[ryancwalsh]

I see from #49337 (reply in thread) that I was using FlatCompat, but it has been a long time, so I don't remember anything that isn't documented above.

If I recall, I probably kept using original eslint configs instead of the new flat style. Switching my projects to flat config was taking more time than it was worth.

[jeremy-code]

EDIT again:

I have created a package eslint-config-next-flat (Source code) that is (roughly) a port of the eslint-config-next for FlatConfig. It seems to work perfect for TypeScript projects (not sure about native JavaScript since it requires Babel parser and I don't have a complicated vanilla JS Next.js project to try it out with).

Just another option whilst we wait for the updated config.

---

EDIT:

After some more research, I believe the best options thus far until Next.js releases a flat config is:

eslint.config.mjs

// flat compat
import url from "node:url";
import eslint from "@eslint/js";
import { FlatCompat } from "@eslint/eslintrc";

const __dirname = url.fileURLToPath(new URL(".", import.meta.url));
const compat = new FlatCompat({ baseDirectory: __dirname });

/** @type {import('eslint').Linter.FlatConfig[]} */
export default [eslint.configs.recommended, ...compat.extends("next")];

or (but you miss out on setting other eslint rules and parsing, and just get access to the default nextjs rules)

import eslint from "@eslint/js";
import next from "@next/eslint-plugin-next";

/** @type {import('eslint').Linter.FlatConfig[]} */
export default [
  eslint.configs.recommended,
  {
    plugins: {
      "@next/next": next,
    },
    rules: {
      ...next.configs.recommended.rules,
    },
  },
];

you can also just use the legacy config and not upgrade to eslint v9, which probably is the best idea for maximum compatability (i had some issues using FlatCompat in a monorepo)

---

Hello, sorry for reviving an answered discussion but I have discovered an (external) package that offers the Next.js rules for use in ESLint Flat config. Not affiliated with them at all -- discovered it in use on the discord.js repo (discord.js/eslint.config.js).

import next from 'eslint-config-neon/flat/next.js';

from ESLint Config Neon: https://github.com/iCrawl/eslint-config-neon

FlatCompat is also an option

[mrcaidev]

ESLint has just released @eslint/compat, which looks much more elegant.

// eslint.config.js
import { fixupConfigRules } from "@eslint/compat";
import { FlatCompat } from "@eslint/eslintrc";

const compat = new FlatCompat();

/** @type {import("eslint").Linter.FlatConfig[]} */
const config = [
  ...fixupConfigRules(compat.extends("next/core-web-vitals", "prettier")),
  { ignores: [".next"] },
];

export default config;

This works fine, until --cache is passed to ESLint, when ESLint would fail and give the following error. Any ideas?

Error: Could not serialize parser object (missing 'meta' object).
    at Object.value (/home/mrcaidev/oauth/node_modules/.pnpm/[email protected]/node_modules/eslint/lib/config/flat-config-array.js:325:27)
    at stringify (/home/mrcaidev/oauth/node_modules/.pnpm/[email protected]/node_modules/json-stable-stringify-without-jsonify/index.js:25:25)
    at module.exports (/home/mrcaidev/oauth/node_modules/.pnpm/[email protected]/node_modules/json-stable-stringify-without-jsonify/index.js:68:7)
    at hashOfConfigFor (/home/mrcaidev/oauth/node_modules/.pnpm/[email protected]/node_modules/eslint/lib/cli-engine/lint-result-cache.js:50:75)
    at LintResultCache.getCachedLintResults (/home/mrcaidev/oauth/node_modules/.pnpm/[email protected]/node_modules/eslint/lib/cli-engine/lint-result-cache.js:116:30)
    at /home/mrcaidev/oauth/node_modules/.pnpm/[email protected]/node_modules/eslint/lib/eslint/eslint.js:896:41
    at Array.map (<anonymous>)
    at ESLint.lintFiles (/home/mrcaidev/oauth/node_modules/.pnpm/[email protected]/node_modules/eslint/lib/eslint/eslint.js:868:23)
    at async Object.execute (/home/mrcaidev/oauth/node_modules/.pnpm/[email protected]/node_modules/eslint/lib/cli.js:500:23)
    at async main (/home/mrcaidev/oauth/node_modules/.pnpm/[email protected]/node_modules/eslint/bin/eslint.js:153:22)

[dir]

A couple differences between my setup and yours I notice off the bat @jkaleshi14:

1. I am using eslint 8.57.0
2. I'm using NPM, not pnpm
3. I can't quite tell, but it looks like you're using CJS. My eslint config is eslint.config.mjs.

I have a hunch that addressing 3 on your end might fix it. But, could be one of the many other externalities as well.

[jkaleshi14]

@dir Thanks that fixed my issue

[r34son]

@dir Thanks that fixed my issue

Could you share fix, please

[dir]

@r34son I believe I already did, refer to my previous message.

[timtucker-dte]

See the notes here on the root cause for why the errors about meta are occurring -- Next.js isn't following the spec for custom parsers and is omitting the "meta" section when it re-exports the parser from @babel/eslint-parser:
eslint/eslint#19080

Tried to report as an issue, but it got auto-closed because the Next.js repository apparently isn't considered a valid link to reproduce.
#72833

[dir]

Wish the Vercel team prioritized this a bit higher. It's a fairly small lift but is impacting the developer experience for a lot of us.

If Next is striving so aggressively to use the newest standards (RSC, server actions, etc), can we not reflect that same mindset with things as small as our ESLint configs?

[poksme]

I wrote a setup guide for Eslint 9 with Next.js detailing my approach to flat config with Next.js : Eslint 9 & Next.js — Setup Guide

Also for a TLDR; check my comment here

[boning-w]

For anyone who want try eslint 9 flat config in Nextjs. Make sure to backup your old .eslintrc.json file, then try:

See: https://eslint.org/docs/latest/use/configure/migration-guide#migrate-your-config-file

npx @eslint/migrate-config .eslintrc.json

This will create a eslint.config.mjs for you.

Then install some packages @eslint/eslintrc, @eslint/js, etc.

Then run npm run lint to see if it work.

Works for me in Next.js 15.

  "dependencies": {
    "next": "^15.0.1",
    "react": "^18",
    "react-dom": "^18"
  },
  "devDependencies": {
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "@eslint/eslintrc": "^3.1.0",
    "@eslint/js": "^9.13.0",
    "eslint": "^9.13.0",
    "eslint-config-next": "^15.0.1",
    "postcss": "^8",
    "tailwindcss": "^3.4.1"
  }

[mdillgen]

@boning-w The migration went smoothly for me. Even the paths of the deprecated .eslintignore are taken into account!

[bdlowery]

Wow. This is SO MUCH BETTER than the .eslintrc.json version.

Output from npx @eslint/migrate-config .eslintrc.json

import path from "node:path";
import { fileURLToPath } from "node:url";
import js from "@eslint/js";
import { FlatCompat } from "@eslint/eslintrc";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const compat = new FlatCompat({
    baseDirectory: __dirname,
    recommendedConfig: js.configs.recommended,
    allConfig: js.configs.all
});

export default [...compat.extends("next/core-web-vitals"), {
    rules: {
        "react/no-unescaped-entities": "warn",
    },
}];

versus my .eslintrc.json file:

{
	"extends": "next/core-web-vitals",
	"rules": {
		"react/no-unescaped-entities": "warn"
	}
}

Not. This sucks. I'll just do ESLINT_USE_FLAT_CONFIG=false.

[isaacbowen]

😂 😂 😂

[corradin]

Soooo, on 18 March 2025 a named export has been added, allowing you to do this:

import { flatConfig } from '@next/eslint-plugin-next';

export default {
  ...flatConfig.recommended,
  ...flatConfig.coreWebVitals,
};

Thank you @SukkaW and @gaojude 😍😍😍

[ya2s]

How will next/typescript be handled?
Will the document not be updated to this style?

[SukkaW]

next/typescript

@ya2s next/typescript lives in eslint-config-next, not in eslint-plugin-next. Notice the difference between -config- and -plugin- here.

eslint-config-next has some extra hacks that can not be migrated to flat configs.

[ShueiYang]

Sooo in case people try to set up the flat config with the new typescript-eslint instead of next/typescript at this moment looks like this setup work:

import eslint from "@eslint/js";
import tseslint from "typescript-eslint";
import { flatConfig } from "@next/eslint-plugin-next";
import eslintPluginReactHooks from "eslint-plugin-react-hooks";
import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";

export default tseslint.config(
  flatConfig.recommended,
  flatConfig.coreWebVitals,
  {
    files: ["**/*.ts", "**/*.tsx"],

    extends: [
      eslint.configs.recommended,
      tseslint.configs.recommended, // or more strict config (e.g. `configs.recommendedTypeChecked`)
      //... other configs 
      // For my useCase I put on the last `eslint-plugin-prettier/recommanded` that combine in one go 
      // with `eslint-config-prettier` So i didn't install eslint-config-prettier.
      eslintPluginPrettierRecommended,
    ],
    
   // Skip this if you don't use `eslint-plugin-react-hooks`
    plugins: {
      "react-hooks": eslintPluginReactHooks,
    },

    languageOptions: {
      // TypeScript ESLint parser for TS files
      parser: tseslint.parser,
      parserOptions: {
        project: "./tsconfig.json",
        ecmaVersion: "latest",
        sourceType: "module",
        ecmaFeatures: {
          jsx: true,
        },
        // the 4 keys above in the parserOptions may be replaced with the 2 options below
        // projectService: true,
        // tsconfigRootDir: import.meta.dirname,
      },
    },
   
   // Custom rule to overwrite/modify or to disable if necessary 
    rules: {
      //...
    },
  },
);

[quanghuynt14]

I was exhausted from dealing with ESLint setup when I came across your comment. I did the exact same thing but ran into this error:
ConfigError: Config (unnamed): Key "extends": This appears to be in eslintrc format rather than flat config format.

Here's how I fixed it:

import eslintPluginNext from "@next/eslint-plugin-next";
import tseslint from "typescript-eslint";
import eslintPluginReactHooks from "eslint-plugin-react-hooks";
import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";

const eslintConfig = [
  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
  eslintPluginNext.flatConfig.recommended,
  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
  eslintPluginNext.flatConfig.coreWebVitals,
  ...tseslint.configs.recommendedTypeChecked,
  eslintPluginPrettierRecommended,
  {
    plugins: {
      "react-hooks": eslintPluginReactHooks,
    },

    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        project: "./tsconfig.json",
        ecmaVersion: "latest",
        sourceType: "module",
        ecmaFeatures: {
          jsx: true,
        },
      },
    },
  },
];

export default eslintConfig;

[ShueiYang]

Oh ok 🤔 you have this error with the config method ? in this case maybe you can also do something like this:

 export default tseslint.config(
   eslintPluginNext.flatConfig.recommended,
   eslintPluginNext.flatConfig.coreWebVitals,
   tseslint.configs.recommendedTypeChecked,  // or spread...

  //...

This is how i set up without framework with React and Vite, the config method is optional ofc, they explain why they recommend it from there doc here https://typescript-eslint.io/packages/typescript-eslint#config