Community Feedback: Pain Points

[bradzacher]

This discussion is intended to be a general thread where we can collect some feedback from users. We've recently seen some unstructured complaints and critiques in other repo discussions and on twitter - which is hard for us to action because we can't easily engage or collect more information in those places (off-topic spam or 140 character limit).

Discussion threads here will let us organise a bit without forcing everyone to go through filing a new issue with a template.

So please provide your feedback. Let us know what you find difficult about using TypeScript with ESLint. Please provide more than a sentence to help us understand. If you can add some examples that would be great.

You don't need to think about or provide any solutions to the problem - leave that to us! (but feel free to provide them if you want!)

We may not be able to respond to everyone, but be sure that every comment will be read by maintainers and will help us to improve the ecosystem.

[arendjr]

The main annoyance for me is how typescript-eslint overrides lint rules that are part of the ESLint core rules itself. Our config has a bunch of definitions like this:

module.exports = {
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  // If adding a typescript-eslint version of an existing ESLint rule,
  // make sure to disable the ESLint rule here.
  rules: {
    // TypeScript's `noFallthroughCasesInSwitch` option is more robust (#6906)
    "default-case": "off",
    // 'tsc' already handles this (https://github.com/typescript-eslint/typescript-eslint/issues/291)
    "no-dupe-class-members": "off",
    // 'tsc' already handles this (https://github.com/typescript-eslint/typescript-eslint/issues/477)
    "no-undef": "off",

    // Add TypeScript specific rules (and turn off ESLint equivalents)
    "@typescript-eslint/consistent-type-assertions": "warn",
    "no-array-constructor": "off",
    "@typescript-eslint/no-array-constructor": "warn",
    // more of these…
  }
}

Note that this is based on an ejected create-react-app config from a long time ago, and since we do have a bunch of customized rules we ended up owning this. But preferably we wouldn’t care, we’d just configure our custom rules and call it a day.

But to me this shows there’s an inherent tension because of the fact that ESLint’s core doesn’t recognize TypeScript (hence the need for a custom parser) and its rules don’t either. This also leaks into the ecosystem, because when trying out some rule from NPM you often don’t know whether it’ll play nicely with TypeScript or not.

If TypeScript support were first-class (see Deno or Rome), this would not be necessary.

[bradzacher]

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.

[e-oz]

For the authors of @typescript-eslint/prefer-for-of:
https://benlesh.com/posts/forEach-is-a-code-smell/

[bradzacher]

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

[bradzacher]

We have clear and explicit documentation on how we do versioning and what we consider a breaking change.

https://typescript-eslint.io/users/versioning

Changes to the recommended set are only done in a major.

[RemyMachado]

Here is some feedback:

I used this library a while ago, but today I wasn't able to configure it again on a new project.

The documentation assume you know eslint and therefore you are able to configure typescript-eslint. I thought the documentation would help getting started from scratch, but really you have to guess on how to plug it.

Do you need a plugin? Do you need a different config file? Do you need to extend eslint configuration?

After reading the whole documentation you realise that it won't tell you how to set it up and that these answers are hidden behind this vague title:

I understand that it's not this documentation's job to explain how eslint works, but pinpointing mandatory steps or at least stating that eslint knowledge is required to go further would be great.

[JoshuaKGoldberg]

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.

[RemyMachado]

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.

[RemyMachado]

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,
);

[bradzacher]

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.

[RemyMachado]

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!