Implement Flat Config

[nzakas]

This issue describes the implementation plan for eslint/rfcs#9, which will take place in several phases:

Phase 1: Extract current config system

• Create new GitHub repository (eslint/eslintrc)
• Copyeslintrc source files and tests into new GitHub repository
• Create Jenkins release job for @eslint/eslintrc
• Publish @eslint/eslintrc to npm
• Update ESLint to use @eslint/eslintrc
• Remove in-memory filesystem from tests
• Update CLIEngine to use CascadingConfigArrayFactory from @eslint/eslintrc

Phase 2: Implement flat config with eslintrc compatibility

• Create the FlatCompat class in eslint/eslintrc repository
• Create FlatConfigArray to represent simple configs
• Update Linter class to understand FlatConfigArray objects
• Ensure Linter#defineRule and Linter#definePlugin throw errors when using FlatConfigArray
• Add context.languageOptions in backwards-compatible way to context in Linter
• Ensure context.parserPath still works in Linter for FlatConfigArray (for now)
• Create FlatRuleTester to allow rule testing with FlatConfigArray format
• Create FlatESLint class to mirror ESLint class but use eslint.config.js instead
• Change Request: Matching behavior in flat config #15661
• Change Request: Config base path in flat config #15683
• Overrides of ignore patterns #15687
• Implement caching
• Update cli.js to search for eslint.config.js file and use FlatESLint if found (ESLint if not)
• Ensure invalid CLI flags cause errors when using flat config (for example, --resolve-plugins-relative-to)
• Switch eslint/eslint repo to use flat config
• Document flat config
• Release ESLint with eslintrc compatibility
• Bug: [new config system] Patterns cannot re-ignore #16416
• Bug: [new config system] Directories cannot be unignored #16415
• Bug: [new config system] Inconsistent behavior with ignored directory #16414
• Bug: [new config system] Files outside cwd were not found #16413
• Bug: FlatESLint getRulesMetaForResults fails on anonymous files when option cwd is set #16410
• Bug: FlatESLint getRulesMetaForResults fails on messages without a ruleId #16402
• Bug: [new config system] baseConfig option is unused in FlatESLint #16341
• Bug: [new config system] Unexpected glob behavior in FlatESLint #16340
• Bug: [new config system] path to a directory can still lint files outside that directory #16299
• Bug: [new config system] unmatched individual patterns are not reported #16275
• Bug: [new config system] globs are ignoring dot files #16265
• Bug: [new config system] .eslintignore doesn't work like .gitignore #16264
• Change Request: Specifying files and ignores for eslint:recommended/eslint:all #16537
• Bug: [flat config] Caching is not supported when parser is an object #16875

Phase 3: Compatibility testing

• Work with typescript-eslint to switch to new format and ensure it works correctly (pull request)
• Work with eslint-plugin-import to switch to new format and ensure it works correctly (@mdjermanovic) [Fix] pass languageOptions through in child context import-js/eslint-plugin-import#2829 Support eslint flat config import-js/eslint-plugin-import#2873
• Work with eslint-config-airbnb to switch to new format and ensure it works correctly (@mdjermanovic)
• Work with eslint-config-standard to switch to new format and ensure it works correctly (pull request]
• Work with eslint-plugin-n to switch configs to new format and ensure it works correctly (@mdjermanovic) (pull request)
• Work with eslint-plugin-vue to switch configs to new format and ensure it works correctly (pull request)
• Work with eslint-plugin-react to switch configs to new format and ensure it works correctly (@mdjermanovic) (pull request)
• Switch ESLint config to load external configs/plugins without FlatCompat
• Release ESLint with extended compatibility

Phase 4: General availability (v9.0.0)

• Write blog post about flat config format
• Output warning when people use eslintrc files
• Switch documentation so eslint.config.js is the default and recommended format (link to legacy eslintrc docs from the same page)
• Switch Linter to use flat config by default
• Switch documentation for shareable configs to flat config format (links to legacy docs included)
• Switch documentation for plugins to flat config format (links to legacy docs included)
• Omiting any file/dir positional parameter to CLI does not give an error #14308
• Rename ESLint class to LegacyESLint and rename FlatESLint to ESLint
• Delete RuleTester class and rename FlatRuleTester to RuleTester
• Update api.js to export new values for ESLint and RuleTester
• Switch shouldUseFlatConfig() to return true except if ESLINT_USE_FLAT_CONFIG is false.
• Release ESLint with GA flat config

Phase 5: Remove eslintrc (v10.0.0)

• Remove old CLI flags
• Remove context.parserPath, context.parserOptions, context.globals in Linter
• Remove configType constructor option for Linter; throw error if found.
• Report an error when eslint-env config comment is used
• Remove eslintrc support
• Remove eslintrc documentation
• Delete FlatESLint class
• Delete LegacyESLint class
• Switch shouldUseFlatConfig() to always return true
• Release ESLint without eslintrc 🎉

[nzakas]

Update: Most of the CLIEngine tests are so tightly coupled to the existing file structure (overriding and stubbing require imports and then trying to use an in-memory file system) that there's just no way I can get all of the tests to pass. I suspect that the tests aren't actually testing what we think they are due to this complexity. It seems my only path forward is to leave the eslintrc functionality in place in the eslint repo and then make a copy in the eslintrc repo. We will just have to focus on removing the eslintrc functionality when we remove CLIEngine.

[nzakas]

I'm going to make one more pass but using a physical file system instead of an in-memory filesystem to see if I can disentangle the tests. If that doesn't work, I'll do a more minimal extraction and move on.

[bradzacher]

I think it would be a good idea to include @typescript-eslint in the Phase 3 list.

IMO onboarding the project as early as possible is a hard requirement for the workstream. Without ts-eslint's onboarding the majority of ESLint users won't able to transition to flat configs without needing to use the compatibility tooling.

For reference - by weekly download volume @typescript-eslint/eslint-plugin users make up over 65% of ESLint users and @typescript-eslint/parser users make up over 70% of ESLint's users.
(plugin = 19.2m / parser = 21m / eslint = 28.8m)

It would be a real shame if most users' first experience with new config system involves reaching for the compatibility APIs. Making sure that doesn't happen should be a top priority!

Feel free to chat with us (cc @JoshuaKGoldberg and @JamesHenry)!

---

Separately but very related to the above - I'd also suggest including eslint-plugin-import for the same reasons given that it is similar in size (17.1m - ~60%).

[kirill-konshin]

Could not agree more @bradzacher. The success of tools like Next.js, Jest, Prettier and even Create React App proves that many users want simple tools, they need fast onboarding and prefer opinionated presets.

It's great to have a configurable tool, but for majority of users thousands of options are overwhelming. People simply do not have time to dig into nuances, they need a solution.

In my opinion, ESLint should provide some dead easy way to kick off a fresh project with all necessary dependencies. Something like npm install eslint && eslint init recommended. Look at the guide https://eslint.org/docs/latest/user-guide/getting-started and https://eslint.org/docs/latest/user-guide/configuring/configuration-files-new — and imagine what most users think while reading this...

[nzakas]

@bradzacher will do. The intent is to use phase 3 to test the ecosystem in general.

@kirill-konshin this is off topic for this issue, but you can use npm init @eslint/config. It’s listed right on eslint.org. 😄

[Shinigami92]

Thanks a lot to @sxzz since eslint-define-config v1.8.0 Flat ESLint Config is officially supported by my plugin 🚀

[mahnunchik]

Any news?

[nzakas]

@mahnunchik you can look at the checklist in the original comment to see the current progress.

[karlhorky]

• Work with eslint-plugin-react to switch configs to new format and ensure it works correctly

@nzakas now that the new config format has been added in jsx-eslint/eslint-plugin-react#3429, should this checkbox in Phase 3 be checked?

[ljharb]

eslint-plugin-react v7.32.0 has been released, with flat config support - but only less than 12 hours ago. It's probably wise to wait a bit longer to make sure it actually does work correctly :-)

[nzakas]

This is a tracking issue and not the best place to ask for help. Please open a discussion instead.

[CallMeLaNN]

This is a tracking issue and not the best place to ask for help. Please open a discussion instead.

My intention was to get a chance to help or send PR for some plugins since I already study the code of the flat configs on both Eslint and some plugins. It could be the way to start contribute to the community on the phase 3.

Anyway, in that case, you may update somewhere about the concern above whenever Eslint team is ready.

[nzakas]

@CallMeLaNN that's great, we'd appreciate the help...but this is still not the right place for that type of question. Happy to continue in a separate discussion.

[nzakas]

Folks - if you have questions about flat config, please open a discussion rather than commenting here. This issue is for tracking purposes only.

[mdjermanovic]

• Remove context.parserPath, context.parserOptions, context.globals in Linter

Does context.globals exist?