We do have an existing config which turns off base ESLint rules that are already checked by TS (config docs, config contents) which should save you a bunch of config lines!

As for the other issue of disabling core rules in favour of extension rules - yeah sadly that's just something that can only be truly fixed by ESLint code supporting TS syntax in linting so that we can do-away with extension rules entirely.

Solutions I've mused about that don't work well/at all:

• physically override the core rule with our own create so that you need only require our plugin
  • bad because it's indiscriminate - all JS code would also get the extension then
  • also just smelly and hacky
  • also doesn't really work because some extensions require type information.
• provide a config that turns on all extension rules (and turns off all related base rules)
  • this then inverts the problem - you now have to turn off a bunch of extension rules to get the config you want!
  • as before - this can also be a problem if you aren't using type-aware linting - you'd have to turn off the extension to instead turn on the base rule.
• provide a config util to "fix" your config so that it automatically turns on extension rules
  • falls over due to config extends - it's non-trivial to correctly resolve a config along with its dependencies.
  • difficulty here due to us not knowing what parts of a config apply to TS files and what apply to JS files.
  • with the new "flat config" system, this could actually become a real option because ESLint no longer does any loading and instead configs are required in the config file. We'll have to wait-and-see.

I'm not quite sure how this is related to pain points - could you please elaborate?

Thanks @RemyMachado, that's good feedback! Can I ask - do you recall roughly when you went through the docs?

We revamped the Getting Started guide a fair bit ƒor ESLint's flat config (#8423, #8507) so it'd be good to know if the new docs structure still could use work for first-timers.

I would say it was more than a year ago.

The flat config is great and easy to understand, but I think we are missing crucial directions on how to do the rest (plugin, extension, second config file etc.), because the flat config by itself won't suffice to start a project with typescript-eslint.

I may have found the issue with my config. It started working when I deleted the flat file config.

Should we only keep one file? It's not clear.
I was using both .eslintrc.json and eslint.config.js, because I couldn't figure out how to declare rules in the flat config.
If so, it would make sense to give several examples, including rule definition rather than this two liner:

export default tseslint.config(
  ...tseslint.configs.strict,
  ...tseslint.configs.stylistic,
);

It sounds to me like you came to our docs expecting an explainer on how to migrate to flat configs and/or a high level guide on how to use flat configs.

But that isn't the intention of our quick start guide. Instead the intention is, as stated in the optioning paragraph (Emphasis mine)

This page is a quick-start for ESLint's new "flat" config format to go from zero to linting with our recommended rules on your TypeScript code as quickly as possible.

We're not looking to be an alternative to eslint's docs - instead we are just trying to fill the very common pain-point of "I have no setup and I want one with as little effort as possible".

The reason we link the ESLint docs is because they really are the best resource to explain how to do anything with a config file. We could provide some examples but they would merely be duplicates on top of the ones shown in eslint's own docs.

It sounds to me like you came to our docs expecting an explainer on how to migrate to flat configs and/or a high level guide on how to use flat configs.

Exactly!

This page is a quick-start for ESLint's new "flat" config format to go from zero to linting with our recommended rules on your TypeScript code as quickly as possible.

It makes sense now that I understood that the issues were related to eslint rather than typescript-eslint.

Even thought I've been using ESLint for years, I'm not very familiar with it and I didn't know about the new config format.
My error was mistaking ESLint with typescript-eslint and thinking the new format was specific to this very own package, when really its written on the first line:

This page is a quick-start for ESLint's new "flat" config format

Thanks for the clarifications!

Not at the moment. We just build on top of ESLint, and ESLint manages all configuration file loading.

...but good news: eslint.config.ts files are coming to ESLint very soon! eslint/eslint#18440 is in review now. 🚀

Note that in the new versions of eslint this is now possible!

Uh oh! @RobinTail, the image you shared is missing helpful alt text. Check #6121 (comment).

Alt text is an invisible description that helps screen readers describe images to blind or low-vision users. If you are using markdown to display images, add your alt text inside the brackets of the markdown image.

Learn more about alt text at Basic writing and formatting syntax: images on GitHub Docs.

🤖 Beep boop! This comment was added automatically by github/accessibility-alt-text-bot.

I'm not quite sure how to interpret this feedback.

You want more releases?
Less releases?
The right amount of releases?

We're looking for constructive feedback in this forum - things we can action and improve. But on the surface this just seems like venting?

@bradzacher ignore it, it's just an ungrateful useless waste of time. Every release is welcomed and appreciated!

@bradzacher

I'm not quite sure how to interpret this feedback.

You can interpret it this way: all good with version 8, it works well; I'd like the stable version to be released ASAP, preferably three months ago.
Thank you for all the effort! 👍

I would add, flattening logic was also recently added so that you don't have to care whether included configs are arrays or single objects (#10333). In case that was a point of confusion as well

One the one hand, it's great that you add this convenience function. I would still argue that:

1. @andersr's complaint is valid, in that it leaves you hanging a little bit in terms of getting help from ESLint docs, since configuration is in a different format.
2. It's a good argument that ESLint's flat file config still has some massive gaps in DX, and ideally, DX improvements to the config file format would go to the source, rather than this function, which feels like a workaround to ESLint behavior, rather than working with what ESLint provides out of the box. Have you talked to the ESLint team about the need for this function?

One the one hand, it's great that you add this convenience function. I would still argue that:

1. @andersr's complaint is valid, in that it leaves you hanging a little bit in terms of getting help from ESLint docs, since configuration is in a different format.

2. It's a good argument that ESLint's flat file config still has some massive gaps in DX, and ideally, DX improvements to the config file format would go to the source, rather than this function, which feels like a workaround to ESLint behavior, rather than working with what ESLint provides out of the box. Have you talked to the ESLint team about the need for this function?

The typescript-eslint maintenance team has extensively advocated for these types of DX improvements upstream, with varying degrees of success. A few miscellaneous examples

• Change Request: Flat config - allow nested arrays by automatically flattening a flat config array eslint/eslint#18040
• Change Request: Flat config extends eslint/eslint#19116
• feat: Flat config extends eslint/rfcs#126 - Note that it looks like we'll eventually get the flattening behavior upstream, as well as the "extends" key, but quite possibly with different semantics.
• Change Request: Alias and later rename block-level (non-global) "ignores" to "exclude" eslint/eslint#19154
• Request: backporting flat config bug fixes to v8 eslint/eslint#17966

The eslint team decided that flat configs would be an exported array. This is great for pure, untyped JS! But it sucks if you want typechecking (and thus features like intellisense, autocomplete, hover docs, etc) cos you have to annotate the array with a JSDoc comment to get the features.

So to make it dead simple to have typechecking we provide an identity function. That way people don't need to fuss with JSDoc and can just write JS code and not think about the types.

We made it a variadic function (a function that takes any number of arguments) instead of a function that accepts an array as a single argument because TS can provide better errors with a variadic function. TS tends to type an entire array as its elements - so when you make a mistake TS errors on the entire array instead of at the actual error. But a variadic function TS can granulalry error on the individual config object providing a better DevX.

Though its worth noting that as Kirk mentioned - we now do array flattening which means you can write export default tseslint.config([......]) and it'll work the same as export default tseslint.config(......) which will work the same as export default [......].

Also as kirk said - we communicate with and suggest improvements to the ESLint core team regularly. Our maintenance team submits enhancements issues, bug reports, RFCs and PRs. Josh G is also a member of the committer team for eslint.

We work to influence the core team to provide a better DevX where we can. And where we disagree we will build what we can so that we can lead through example.

Have you read the package docs? This should answer many of your questions
https://typescript-eslint.io/packages/typescript-eslint

Especially when that package doesn't provide typings, the typings are inferred in a way that makes them incompatible with the typescript-eslint typings.

Incompatible with any typings actually. It's the problem with inferred types. The solution is to either declare types yourself or use a @ts-expect-error.

Alternatively, why are you not importing and reusing typings from ESLint?

Many reasons.

ESLint didn't own their types until very, very recently. Before that it was in DefinitelyTyped.

When things were in DT - owning our types makes it a lot easier for us to work because we can make changes and fix bugs without waiting for the very very slow DefinitelyTyped merge workflow.

Additionally if we relied on the DT types we'd have less control over the types the user gets - they could install any number of versions and we'd have to try and support a large range. But by owning our types we know exactly what types each release uses.

We also provide a different AST and there isn't a good, clean way to define the types in a way that would work with multiple ASTs. It was much easier to just fork the types.

Additionally we provide our own scope analyser and again it's not possible to integrate this into the types. Forking allows us to do so easily.

Forking also gives us the ability to add non-standard properties trivially. For example we've added many properties to make documentation generation easier for rules.

We also declare types that are intended to make it easier for people to write configs. Eslint's types are intended to strictly define every single state that can be defined. Ours provides a nicer DevX.

I could go on. Many reasons that maintaining our own types is good for us.

Either way, with every ESLint related package now doing their own thing, types will remain to be incompatible. I'd rather see you working together with the main ESLint maintainers to get to a point where you both are happy with the typings, rather than competing against them for the best typings.

End users (which is us) don't want to have to deal with competing incompatible stuff when we "have to" use them together. With all due respect, your explanation gives off a strong 15 standards vibe.

We also are accepting PRs to help improve performance if someone wants to help us investigate and improve things.

A few things:

@bradzacher

Have you checked out our FAQ?

@JoshuaKGoldberg

a lot of folks get through our docs without reading up on this

I'm a nerd who reads the docs. I'm aware there is a performance penalty for using types, and I suspected that "parsing" was also creating a TypeScript project. That said, the docs say this:

We strongly recommend you do use type-aware linting

and they also say...

Most of our users do not mind this cost as the power and safety of type-aware static analysis rules is worth the tradeoff. Additionally, most users primarily consume lint errors via IDE plugins which, through caching, do not suffer the same penalties. This means that generally they usually only run a complete lint before a push, or via their CI, where the extra time often doesn't matter.

I can't speak to what happens for most users. But, I wholly agree with this statement made by @kirkwaiblinger:

The marginal cost of performance of enabling a rule that uses type information is generally insignificant compared to the cost of enabling type information on the first rule (or first few rules) that uses type information (due to type info caching).

My experience thus far is that any type-aware linting has a cost that's incredibly large, and ultimately not worth it. I've worked for companies with projects of a size that I would call typical, a monorepo with some backend packages and some frontend ones. Using type-aware linting can cause the VSCode ESLint plugin to freeze up entirely. Because it takes so many seconds to lint a page, then enabling "lint on save" can ruin your workflow. If you're very careful, and re-configure the root tsconfig.json to not include files in the monorepo, even if you're extending, and you're careful to limit the scope of ESLint files so that the ESLint plugin isn't overwhelmed, and you disable any extensions you don't absolutely need, then you can prevent VSCode from locking up.

Aside from the above issue, it just takes a super duper long time even linting the files you want to, or linting the project after a CI error. Being hand-wavy and saying that an error that occurs in CI doesn't matter in terms of time I think is just not true. The time can add up, where people are waiting on builds to finish to deploy, and then once you have an issue, context-switching back locally to find / solve that problem. Which can then significantly alter your flow of how many things you can get done in a day.

What's tricky is that the docs also don't mention one key detail: if you disable every type-aware linting RULE, you will NOT disable type-aware linting. I discovered that one thing the disable type-checked rules config is doing is ALSO disabling the project and projectService properties. A developer may reason this backwards by noting the docs say how to turn type checking ON, but it's not immediately obvious that if a user is using NO type-checking rules, they may still incur a type-checking performance penalty.

So, my personal preference would be that this project be more clear that type-checking linting is PROBABLY not necessary, or, at least, more strongly infer that someone should carefully weigh the trade-offs between performance / time costs and the marginal benefits of those few type-aware rules (unless you think there are specific type-aware rules that are incredibly valuable to a developer, which would be good to state outright).

related: #8506

this project be more clear that type-checking linting is PROBABLY not necessary

Responding only to this part for now: this is the ~opposite conclusion of our intent in the docs 😄. We're trying to convey that type-checked linting is VERY USEFUL for MOST projects and you should always at least strongly consider it.

My experience thus far is that any type-aware linting has a cost that's incredibly large, and ultimately not worth it.

Anecdotally this is the opposite of what I've heard from many users at companies with large codebases - and I've spoken to users at a half a dozen large tech companies.

Those that use it love it, but they do hate the perf cost. Those that don't use it lament that they can't use it because the perf cost is too great for them.

The various promise rules are the thing that people most want from my experience as it's the easiest thing to mess up at scale and requires type-aware linting to watch for.

As an example - at Canva our codebase is too big to be able to run type-aware linting. We have 90k TS files. Just doing plain, boring, non-type-aware eslint run parallelised across 30 cores takes us 2 minutes in CI. Additionally our architecture means there isn't a good way to slice and dice distinct units for parallelised type-aware linting.

But we see massive value in type-aware linting so we sought out other ways to use it. We forked this language service plugin so that we could provide type-aware lint errors to engineers without impacting lint times. We don't get CI enforcement but it's often enough to just show the user the errors in their IDE and they will respect the squiggles.

TL;DR - I would strongly, strongly, strongly disagree with the sentiment that type-aware linting is not worth it. It has incredible value in catching real big vectors that are otherwise only catchable via deep and thorough human code reviews (which doesn't ever happen - let's be real).

The question to answer isn't "should I use type-aware linting?" instead it's "how can I enable type-aware linting?"

I'm cautiously optimistic that the new extends config option in 9.22 (out today) will address my needs.

I'm confused.... We have had support for extends in our tseslint.config utility since it was introduced.

This new utility function that eslint is introducing and extends support was added because we suggested it and the implementation was derived from our implementation.

What usecase do you think theirs will cover that ours does not when they are equivalent...?

Ah, I see that the use of extends requires the use of defineConfig which is just another black box.

Not for me.

I want to declare my own configs so I can understand what they do simply by reading the config. That's it.

Yes, the old config format used extends, but it was a single config and extends: 'foo' is declarative and I understand what it does (without needing to read source code).

If you'll allow me, you might look at this discussion as representative of the difference between top-down and bottom-up learners.

I'm a bottom-up-style learner. I find suggestions like "just use tseslint.config()" to be frustrating because I want to understand what is actually happening.

Other people are top-down and are comfortable typing npx create-next-app@latest and never digging any deeper, and are perfectly content.

Yes, the old config format used extends, but it was a single config and extends: 'foo' is declarative

It wasn't actually a single config - extends: "foo" was shorthand for extends: ["foo"].

And note that the configs haven't changed at all. The configs we supply for flat configs are exactly the same as the configs for legacy configs.

From reading your comments - you didn't actually don't have an issue understanding the configs - cos you're able to successfully configure both legacy and flat configs.

The problem is instead that as soon as you add a new language (in your case JSON) everything gets much more complicated and we move into a new realm of config setup where everything changes. Essentially you've hit a rough edge of eslint itself right now.

The new "languages" aren't compatible with rules intended for JS/TS. So now instead of just configuring every rule to always run you have to very specifically constrain all the JS/TS stuff to just the right files. It's a big shift in config style and complexity.

The current tooling doesn't do a great job of showing you what's not working or why. The config inspector can show you but you need to understand how to drive it and you need to understand what it's telling you.

For example your question has been "why is eslint crashing?" and the inspector does technically answer that question - but only if you have a deeper understanding of eslint.

The answer is "it's crashing because you're running JS/TS rules on JSON files" and the config inspector shows you that answer by showing you that you have JS/TS rules running on JSON files. But if you don't understand that concept (that certain rules aren't compatible with certain languages) then that answer will be unobtainable.

The rough edge in eslint here is that realistically the JS/TS rules that don't work on JSON shouldn't run on JSON automatically. It shouldn't be something you need to think about. But sadly eslint isn't there yet with this new languages concept.

Would be worth talking to eslint core about your pain here - I'm sure it's going to be a common pain point and is something they should fix.

Not that I want to "pass the buck" on this but we do not support Vue's language tooling.

We support anything that works when you run tsc on the CLI. If you are using a 3rd party wrapper around typescript, 3rd party IDE extensions, or 3rd party TSC LSP plugins to make your types work - that is outside what we officially support.

Vue has its own, bespoke language tooling which wraps typescript and so we do not support it. Instead the Vue team supports it and provides their own wrappers that integrate their language tooling with our tooling.