Choosing Between Legacy and Flat Config
You'll learn when to pick ESLint's legacy .eslintrc format versus the newer flat config system based on your project's constraints.
The Decision Matrix
Think of this like choosing between a well-worn path and a modern highway—both get you there, but they suit different journeys.
Use Legacy .eslintrc when:
- You're on ESLint v8 or earlier (flat config didn't exist before v8.21.0)
- Your team relies on older plugins that haven't migrated yet
- You have existing projects with deep
.eslintrcsetups and migration isn't justified - Your team is unfamiliar with flat config and stability matters more than modernization
Use Flat Config (eslint.config.js) when:
- You're starting a new project on ESLint v9+ (where it's the default)
- You want better TypeScript support for config files
- You prefer simpler, more explicit configuration without string-based
extends - Your plugins support flat config (check their documentation)
- You value better IDE autocomplete for configuration options
Version Considerations
ESLint v9 made flat config the default. If you're upgrading from v8, you'll need to actively choose whether to migrate. ESLint v8.57.0 supports both systems, letting you test flat config before committing.
Team Factors
Consider your team's learning curve. Flat config is conceptually simpler (plain JavaScript arrays), but it requires understanding the new structure. If your team is already comfortable with .eslintrc and plugin compatibility is uncertain, staying with legacy might reduce friction.
Key Takeaway: Choose flat config for new projects on ESLint v9+ with compatible plugins; stick with legacy .eslintrc for existing projects, older ESLint versions, or when plugin support is uncertain—prioritize stability and team readiness over novelty.