ESLint Flat Config Migration: Moving from .eslintrc to eslint.config.js

ESLint 9 was released in April 2025, and it makes flat config the default. The old .eslintrc format is deprecated and will be removed in ESLint 10. If you have not migrated yet, your lint setup is running in compatibility mode, and every npm install prints a deprecation warning.

This post covers the migration itself: what changes, what stays the same, and the exact eslint.config.js you should write for a typical TypeScript project with React, imports, and Prettier.

The problem with .eslintrc

The .eslintrc format had accumulated a decade of design debt:

extends was a black box. You added "extends": ["airbnb"] and 800 rules appeared. Knowing which ones and overriding them required deep archeology.
plugins and rules were decoupled. You listed a plugin in plugins and then referenced it again in rules with a prefixed name. The connection was implicit and easy to get wrong.
Shareable configs piled on. Each project had a tower of extends (airbnb, prettier, next, typescript) that resolved at runtime with no ability to trace which rule came from where.
Cascading .eslintrc files. Parent directory configs merged with child configs in ways that surprised teams constantly.

Flat config replaces all of this with a single eslint.config.js file that exports an array of flat config objects. Each object is self-contained: it specifies files, rules, plugins, and languageOptions in one place. No inheritance, no merging magic.

What flat config changes

Concept	`.eslintrc`	`eslint.config.js`
Config file	`.eslintrc.json`, `.eslintrc.js`, `.eslintrc.yaml`	`eslint.config.js` (or `.mjs`, `.ts`)
Format	Single object with `extends`, `plugins`, `rules`	Array of flat config objects
Extends	String array, resolved at runtime	Import and spread manually
Env	`"env": { "node": true, "browser": true }`	`languageOptions.globals`
Parser	`"parser": "@typescript-eslint/parser"`	`languageOptions.parser`
Plugins	String array plus prefixed rules	Import the plugin object, reference directly
Overrides	`"overrides": [{ "files": [...], "rules": {...} }]`	Just another config object with `files`
Ignore	`.eslintignore` file	`ignores` property on a config object
Cascading	Merged parent/child `.eslintrc` files	Single file per project, no merging

Before and after: a concrete migration

Here is a typical .eslintrc.json for a TypeScript project with React:

{
  "root": true,
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:import/recommended",
    "plugin:import/typescript",
    "prettier"
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module",
    "project": "./tsconfig.json",
    "ecmaFeatures": { "jsx": true }
  },
  "plugins": ["@typescript-eslint", "react", "react-hooks", "import"],
  "rules": {
    "@typescript-eslint/no-floating-promises": "error",
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/strict-boolean-expressions": "error",
    "react/react-in-jsx-scope": "off",
    "import/no-cycle": "error",
    "import/order": ["error", { "alphabetize": { "order": "asc" } }]
  },
  "settings": {
    "react": { "version": "detect" },
    "import/resolver": { "typescript": true }
  },
  "overrides": [
    {
      "files": ["**/*.test.ts", "**/*.test.tsx"],
      "rules": {
        "@typescript-eslint/no-explicit-any": "off",
        "no-console": "off"
      }
    }
  ]
}

And here is the equivalent flat config:

import js from "@eslint/js";
import tseslint from "typescript-eslint";
import reactPlugin from "eslint-plugin-react";
import reactHooksPlugin from "eslint-plugin-react-hooks";
import importPlugin from "eslint-plugin-import";
import globals from "globals";
import eslintConfigPrettier from "eslint-config-prettier";

export default [
  // Global ignores
  { ignores: ["dist/**", "node_modules/**", "*.config.*"] },

  // Base config: recommended JS rules
  js.configs.recommended,

  // TypeScript config
  ...tseslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,

  // React config
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: {
      react: reactPlugin,
      "react-hooks": reactHooksPlugin,
    },
    languageOptions: {
      globals: { ...globals.browser },
      parserOptions: {
        ecmaFeatures: { jsx: true },
      },
    },
    rules: {
      ...reactPlugin.configs.recommended.rules,
      ...reactHooksPlugin.configs.recommended.rules,
      "react/react-in-jsx-scope": "off",
    },
    settings: {
      react: { version: "detect" },
    },
  },

  // Import plugin
  {
    plugins: { import: importPlugin },
    rules: {
      ...importPlugin.configs.recommended.rules,
      ...importPlugin.configs.typescript.rules,
      "import/no-cycle": "error",
      "import/order": [
        "error",
        { alphabetize: { order: "asc" } },
      ],
    },
    settings: {
      "import/resolver": { typescript: true },
    },
  },

  // Project-specific rules
  {
    files: ["**/*.{ts,tsx,js,jsx}"],
    languageOptions: {
      globals: { ...globals.node, ...globals.browser },
      parser: tseslint.parser,
      parserOptions: {
        project: "./tsconfig.json",
      },
    },
    rules: {
      "@typescript-eslint/no-floating-promises": "error",
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/strict-boolean-expressions": "error",
      "no-console": ["error", { allow: ["warn", "error"] }],
    },
  },

  // Test file overrides
  {
    files: ["**/*.test.{ts,tsx}", "**/__tests__/**"],
    rules: {
      "@typescript-eslint/no-explicit-any": "off",
      "no-console": "off",
    },
  },

  // Must be last: turns off formatting rules
  eslintConfigPrettier,
];

Key differences explained

1. extends is gone. You import configs as objects.

In the flat config world, you do not use strings like "plugin:@typescript-eslint/recommended". Instead you import the config object and spread it into the array:

import tseslint from "typescript-eslint";

export default [
  ...tseslint.configs.recommended,
];

The spread operator is not optional. Each config is an array or an object, and you need to spread arrays to flatten them into the top-level array.

Some packages export their configs differently:

@eslint/js exports js.configs.recommended (a single object)
typescript-eslint exports tseslint.configs.recommended (an array)
eslint-plugin-react uses reactPlugin.configs.recommended.rules

Check each plugin’s migration guide. The pattern varies.

2. env is replaced by languageOptions.globals

The old "env": { "node": true } automatically pulled in global variables for that environment. Now you import from the globals package and spread the ones you need:

import globals from "globals";

export default [
  {
    languageOptions: {
      globals: {
        ...globals.node,
        ...globals.browser,
      },
    },
  },
];

Install globals separately: npm install --save-dev globals. It is not included with ESLint anymore.

3. plugins are imported objects, not strings

Old way: "plugins": ["react"], then "rules": { "react/jsx-key": "error" }.

New way:

import reactPlugin from "eslint-plugin-react";

export default [
  {
    plugins: { react: reactPlugin },
    rules: {
      "react/jsx-key": "error",
    },
  },
];

The key in the plugins object becomes the prefix you use in rule names. If you write plugins: { r: reactPlugin }, rules become "r/jsx-key". Use the convention the plugin expects.

4. overrides are just more config objects

In flat config, every element in the array is an override. Configs with a files property apply only to matching files. Configs without files apply globally. You can repeat this as many times as needed, and the last matching config wins for each rule.

This is more explicit than the old overrides block. It also means you can pull shared configs into separate files:

const testOverrides = {
  files: ["**/*.test.*"],
  rules: { "no-console": "off" },
};

export default [
  js.configs.recommended,
  testOverrides,
  // ...
];

5. ignores replace .eslintignore

The ignores array on a config object tells ESLint which files to skip entirely. Unlike the old .eslintignore, it uses the same glob syntax as files.

Important: a config object with only ignores and no files applies as a global ignore directive. If you add files, the ignores only apply within those files.

// Global ignore: these files are never linted
{ ignores: ["dist/**", "coverage/**"] },

Prettier integration

The eslint-config-prettier package still works, but the import is different:

import eslintConfigPrettier from "eslint-config-prettier";

export default [
  // ... all your other configs ...

  // MUST be last
  eslintConfigPrettier,
];

eslint-config-prettier is now a flat config object (since v10). Spread it as the last element in the array so it can override any conflicting rules from earlier configs.

If you use Prettier as an ESLint rule via eslint-plugin-prettier, stop. The recommended setup is ESLint for code quality and Prettier for formatting, run separately. eslint-plugin-prettier runs Prettier inside ESLint, which makes linting 3x slower and can hide Prettier errors. Run prettier --check in your pre-commit hook and CI instead.

TypeScript in flat config

The typescript-eslint team provides first-class flat config support. Install typescript-eslint (not just @typescript-eslint/eslint-plugin):

npm install --save-dev typescript-eslint

Then import and spread the configs:

import tseslint from "typescript-eslint";

export default [
  ...tseslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: "./tsconfig.json",
      },
    },
  },
];

The recommendedTypeChecked config requires parserOptions.project to be set, just like the old format. If you do not set it, the type-aware rules disable themselves silently.

Performance note: type-aware rules require ESLint to run the TypeScript compiler internally. Expect lint to be 3-5x slower than without types. The typescript-eslint v8+ project service mode caches the TypeScript program between files, which helps. Enable it by setting ESLINT_USE_PROJECT_SERVICE=true in your environment or by using the experimental projectService parser option:

languageOptions: {
  parserOptions: {
    projectService: true,
  },
},

Common migration pitfalls

Config ordering matters

ESLint merges config objects in array order. Later configs override earlier ones for the same rule. Put broad configs first, specific overrides later.

Wrong:

export default [
  { files: ["*.ts"], rules: { "no-console": "off" } },
  { rules: { "no-console": "error" } },   // overrides the one above!
];

Right:

export default [
  { rules: { "no-console": "error" } },
  { files: ["*.test.ts"], rules: { "no-console": "off" } },  // test override wins
];

Missing globals causes false positives

If you use process, require, or __dirname in a Node.js file and do not include globals.node, ESLint flags them as undefined variables. Add languageOptions.globals explicitly.

Spread arrays, not objects

Some config packages export arrays (typescript-eslint), some export objects (@eslint/js). Check the type. Spreading an array inside an array is fine (...arr). Spreading an object inside an array is an error unless the object is iterable.

If you get a runtime error about spreading a non-iterable, check whether the config is an object or an array.

Custom parsers go in languageOptions

Old way: "parser": "@typescript-eslint/parser"

New way:

import tseslint from "typescript-eslint";

{
  languageOptions: {
    parser: tseslint.parser,
  },
}

Same for other parsers like @babel/eslint-parser.

A minimal flat config to start

If you want to migrate incrementally, start with this and add plugins one at a time:

import js from "@eslint/js";

export default [
  { ignores: ["dist/**", "node_modules/**"] },
  js.configs.recommended,
  {
    languageOptions: {
      globals: {
        // Add what you need: import globals from "globals"
        console: "readonly",
        process: "readonly",
      },
    },
    rules: {
      "no-unused-vars": "warn",
      "no-console": ["error", { allow: ["warn", "error"] }],
    },
  },
];

Run npx eslint . and confirm it works. Then add TypeScript. Then React. Then imports. Then Prettier. Each plugin is just another config object at the end of the array.

The takeaway

Flat config is a cleaner model, but the migration is not a find-and-replace. Each concept maps differently: extends becomes spreads, env becomes globals, plugins become imported objects, and overrides become array elements. The ordering of config objects matters in a way that the old .eslintrc did not.

Migrate in stages. Start with the base JS config, verify it works, then layer on TypeScript, React, and imports one by one. Keep Prettier integration as the last element. Test with npx eslint . after each addition.

The final result is a config that is easier to read, trace, and share than the .eslintrc it replaced. Every plugin and rule set is a first-class import at the top of the file. You can see exactly where each rule comes from, comment out a section to debug a false positive, and split configs into reusable modules without the black-box inheritance that made old ESLint so hard to understand.

A note from Yojji

A migration like this touches every file in the repository, touches CI, and touches every developer’s editor. Getting it right means understanding not just the new API but the architectural difference between extends and composition. Yojji’s teams handle these kinds of toolchain upgrades for clients regularly, treating migration work as an engineering discipline with measurable before-and-after states, not a copy-paste job.