Migrating from .eslintrc to Flat Config
You'll learn the practical steps and key differences involved in converting your traditional ESLint configuration to the new flat config system.
Understanding the Migration
Think of migrating from .eslintrc to flat config like moving from a rigid filing cabinet (with strict categories) to a flexible digital system where you define the organization yourself. The new system gives you more control but requires explicit decisions about what was previously automatic.
Key Differences to Address
Configuration Structure: .eslintrc used nested objects with special keys like extends, env, and plugins. Flat config uses a flat array where each object represents a configuration layer you explicitly compose.
Plugin Loading: In .eslintrc, you referenced plugins by name strings ("plugin:react/recommended"). In flat config, you import plugin objects directly as JavaScript modules and reference them explicitly.
File Matching: The old system used overrides arrays with files patterns. Flat config makes every configuration object potentially file-specific using top-level files and ignores keys.
Globals and Environments: Instead of env: { browser: true }, you now import globals from the globals package and spread them into languageOptions.globals.
Migration Steps
- Rename
.eslintrc.*toeslint.config.js - Convert to ES module syntax with
export default [] - Replace string-based plugin references with imported modules
- Move environment settings to explicit
languageOptions.globals - Flatten nested
overridesinto separate array items - Update
extendschains into explicit configuration objects you import and spread - Test thoroughly, as some rule behaviors may shift slightly
Key Takeaway: Migrating to flat config transforms implicit, string-based configuration into explicit, JavaScript-based composition—giving you more power at the cost of initially more verbose setup.