diff --git a/.github/replies.yml b/.github/replies.yml index 0c21b0475525..79fb33754374 100644 --- a/.github/replies.yml +++ b/.github/replies.yml @@ -88,5 +88,5 @@ replies: The configurability also leads to huge fanout [making tests huge, and awful to maintain](https://github.com/typescript-eslint/typescript-eslint/blob/b814e635c1f34139c89e0176727480935dd45cac/packages/eslint-plugin/tests/rules/type-annotation-spacing.test.ts). \ It's for these reasons that [eslint has frozen all stylistic lint rule options, and will not accept any new ones](https://eslint.org/blog/2020/05/changes-to-rules-policies). - See also our [What About Formatting?](https://typescript-eslint.io/linting/troubleshooting/formatting) docs. + See also our [What About Formatting?](https://typescript-eslint.io/users/what-about-formatting) docs. name: Use Prettier diff --git a/docs/getting-started/Legacy_ESLint_Setup.mdx b/docs/getting-started/Legacy_ESLint_Setup.mdx index 6fb80e014e68..9fbc2a2871f6 100644 --- a/docs/getting-started/Legacy_ESLint_Setup.mdx +++ b/docs/getting-started/Legacy_ESLint_Setup.mdx @@ -84,7 +84,7 @@ ESLint will lint all TypeScript compatible files within the current folder, and ## Next Steps -If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx). +If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/faqs/General.mdx). ### Additional Configs @@ -116,7 +116,7 @@ You can read more about these in our [shared configurations docs](../users/Share ### Typed Linting We also provide a plethora of powerful rules that utilize the power of TypeScript's type information. -[Visit the next page for a typed rules setup guide](./Typed_Linting.mdx). +[Visit the next page for a typed rules setup guide](../troubleshooting/typed-linting/index.mdx). ### Documentation Resources diff --git a/docs/getting-started/Quickstart.mdx b/docs/getting-started/Quickstart.mdx index 60cde1ca879d..6c4f0865d818 100644 --- a/docs/getting-started/Quickstart.mdx +++ b/docs/getting-started/Quickstart.mdx @@ -83,7 +83,7 @@ ESLint will lint all TypeScript compatible files within the current folder, and ## Next Steps -If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx). +If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/faqs/General.mdx). ### Additional Configs diff --git a/docs/getting-started/Typed_Linting.mdx b/docs/getting-started/Typed_Linting.mdx index 9f1c89323366..9dade9b0d091 100644 --- a/docs/getting-started/Typed_Linting.mdx +++ b/docs/getting-started/Typed_Linting.mdx @@ -1,7 +1,6 @@ --- id: typed-linting title: Linting with Type Information -pagination_next: getting-started/typed-linting/monorepos --- import Tabs from '@theme/Tabs'; @@ -85,7 +84,7 @@ In more detail: :::caution Your ESLint config file may start receiving a parsing error about type information. -See [our TSConfig inclusion FAQ](../troubleshooting/FAQ.mdx#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). +See [our TSConfig inclusion FAQ](../troubleshooting/faqs/General.mdx#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). ::: With that done, run the same lint command you ran before. @@ -186,7 +185,7 @@ module.exports = { See [the `@typescript-eslint/parser` docs for more details](../packages/Parser.mdx#project). :::note -If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx). +If your project is a multi-package monorepo, see [our docs on configuring a monorepo](../troubleshooting/typed-linting/Monorepos.mdx). ::: ### How can I disable type-aware linting for a subset of files? @@ -266,4 +265,4 @@ This means that generally they usually only run a complete lint before a push, o ## Troubleshooting -If you're having problems getting this working, please have a look at our [Troubleshooting and FAQs page](../troubleshooting/FAQ.mdx). +If you're having problems getting this working, please have a look at our [Troubleshooting FAQs](../troubleshooting/faqs/General.mdx). diff --git a/docs/maintenance/Issues.mdx b/docs/maintenance/Issues.mdx index 525147f88c54..de21f0bbef95 100644 --- a/docs/maintenance/Issues.mdx +++ b/docs/maintenance/Issues.mdx @@ -141,7 +141,7 @@ We avoid features that: - Are only relevant for a minority of users, as they aren't likely worth the maintenance burden - Aren't TypeScript-specific (e.g. should be in ESLint core instead) - Are only relevant with specific userland frameworks or libraries, such as Jest or React -- Are for "formatting" functionality (we [strongly recommend users use a separate dedicated formatter](../troubleshooting/Formatting.mdx)) +- Are for "formatting" functionality (we [strongly recommend users use a separate dedicated formatter](../users/What_About_Formatting.mdx)) #### ✨ Rule Enhancements diff --git a/docs/packages/ESLint_Plugin_TSLint.mdx b/docs/packages/ESLint_Plugin_TSLint.mdx index 91cea06c45a0..920e72b54b42 100644 --- a/docs/packages/ESLint_Plugin_TSLint.mdx +++ b/docs/packages/ESLint_Plugin_TSLint.mdx @@ -10,7 +10,7 @@ sidebar_label: eslint-plugin-tslint > ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. ✨ :::caution -Per [What About TSLint?](../troubleshooting/TSLint.mdx), we highly recommend migrating off TSLint. +Per [What About TSLint?](../users/What_About_TSLint.mdx), we highly recommend migrating off TSLint. See [Getting Started](../getting-started/Quickstart.mdx) for documentation on how to lint your TypeScript code with ESLint. ::: diff --git a/docs/troubleshooting/FAQ.mdx b/docs/troubleshooting/FAQ.mdx deleted file mode 100644 index 066b618c5ed7..000000000000 --- a/docs/troubleshooting/FAQ.mdx +++ /dev/null @@ -1,538 +0,0 @@ ---- -id: faqs -title: FAQs -slug: /troubleshooting/ ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -## I am using a rule from ESLint core, and it doesn't work correctly with TypeScript code - -This happens because TypeScript adds new features that ESLint doesn't know about. - -The first step is to [check our list of "extension" rules here](/rules/#extension-rules). -An extension rule is a rule which extends the base ESLint rules to support TypeScript syntax. -If you find it in there, give it a go to see if it works for you. -You can configure it by disabling the base rule, and turning on the extension rule. -Here's an example with the `semi` rule: - -```json -{ - "rules": { - "semi": "off", - "@typescript-eslint/semi": "error" - } -} -``` - -If you don't find an existing extension rule, or the extension rule doesn't work for your case, then you can go ahead and check our issues. -[The contributing guide outlines the best way to raise an issue](../contributing/Issues.mdx). - -> We release a new version our tooling every week. -> _Please_ ensure that you [check our the latest list of "extension" rules](/rules/#extension-rules) **_before_** filing an issue. - - - -## I get errors telling me "Having many files run with the default project is known to cause performance issues and slow down linting." - -These errors are caused by using the [`EXPERIMENTAL_useProjectService`](../packages/Parser.mdx#experimental_useprojectservice) `allowDefaultProjectForFiles` with an excessively wide glob. -`allowDefaultProjectForFiles` causes a new TypeScript "program" to be built for each "out of project" file it includes, which incurs a performance overhead for each file. - -To resolve this error, narrow the glob(s) used for `allowDefaultProjectForFiles` to include fewer files. -For example: - -```diff title="eslint.config.js" -parserOptions: { - EXPERIMENTAL_useProjectService: { - allowDefaultProjectForFiles: [ -- "**/*.js", -+ "./*.js" - ] - } -} -``` - -You may also need to include more files in your `tsconfig.json`. -For example: - -```diff title="tsconfig.json" -"include": [ - "src", -+ "*.js" -] -``` - -If you cannot do this, please [file an issue on typescript-eslint's typescript-estree package](https://github.com/typescript-eslint/typescript-eslint/issues/new?assignees=&labels=enhancement%2Ctriage&projects=&template=07-enhancement-other.yaml&title=Enhancement%3A+%3Ca+short+description+of+my+proposal%3E) telling us your use case and why you need more out-of-project files linted. -Be sure to include a minimal reproduction we can work with to understand your use case! - -## I get errors telling me "ESLint was configured to run ... However, that TSConfig does not / none of those TSConfigs include this file" - -These errors are caused by an ESLint config requesting type information be generated for a file that isn't included in the TypeScript configuration. - -### Fixing the Error - - - -- If you **do not** want to lint the file: - - Use [one of the options ESLint offers](https://eslint.org/docs/latest/user-guide/configuring/ignoring-code) to ignore files, namely a `.eslintignore` file, or `ignorePatterns` config. -- If you **do** want to lint the file: - - If you **do not** want to lint the file with [type-aware linting](../getting-started/Typed_Linting.mdx): - - Use [ESLint's `overrides` configuration](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#configuration-based-on-glob-patterns) with our [`disable-type-checked`](../users/Shared_Configurations.mdx#disable-type-checked) config to disable type checking for just that type of file. - - - - ```js title="eslint.config.js" - import tseslint from 'typescript-eslint'; - - export default tseslint.config( - // ... the rest of your config ... - { - files: ['**/*.js'], - extends: [tseslint.configs.disableTypeChecked], - }, - ); - ``` - - - - - ```js title=".eslintrc.cjs" - module.exports = { - // ... the rest of your config ... - overrides: [ - { - extends: ['plugin:@typescript-eslint/disable-type-checked'], - files: ['./**/*.js'], - }, - ], - }; - ``` - - - - - Alternatively to disable type checking for files manually, you can set `parserOptions: { project: false }` to an override for the files you wish to exclude. - - If you **do** want to lint the file with [type-aware linting](../getting-started/Typed_Linting.mdx): - - Check the `include` option of each of the TSConfigs that you provide to `parserOptions.project` - you must ensure that all files match an `include` glob, or else our tooling will not be able to find it. - - If the file is a `.cjs`, `.js`, or `.mjs` file, make sure [`allowJs`](https://www.typescriptlang.org/tsconfig#allowJs) is enabled. - - If your file shouldn't be a part of one of your existing tsconfigs (for example, it is a script/tool local to the repo), then consider creating a new tsconfig (we advise calling it `tsconfig.eslint.json`) in your project root which lists this file in its `include`. For an example of this, you can check out the configuration we previously used in this repo: - - [`tsconfig.eslint.json`](https://github.com/typescript-eslint/typescript-eslint/blob/958fecaef10a26792dc00e936e98cb19fd26d05f/tsconfig.eslint.json) - - [`eslint.config.mjs`](https://github.com/typescript-eslint/typescript-eslint/blob/958fecaef10a26792dc00e936e98cb19fd26d05f/.eslintrc.js) - - - -### More Details - -This error may appear from the combination of two things: - -- The ESLint configuration for the source file specifies at least one TSConfig file in `parserOptions.project` -- None of those TSConfig files includes the source file being linted - - Note that files with the same name and different extension may not be recognized by TypeScript: see [`parserOptions.project` docs](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsproject) - -When TSConfig files are specified for parsing a source file, `@typescript-eslint/parser` will use the first TSConfig that is able to include that source file (per [aka.ms/tsconfig#include](https://www.typescriptlang.org/tsconfig#include)) to generate type information. -However, if no specified TSConfig includes the source file, the parser won't be able to generate type information. - -This error most commonly happens on config files or similar that are not included in their project TSConfig(s). -For example, many projects have files like: - -- An `.eslintrc.cjs` / `eslint.config.js` with `parserOptions.project: ["./tsconfig.json"]` -- A `tsconfig.json` with `include: ["src"]` - -In that case, viewing the file in an IDE with the ESLint extension will show the error notice that the file couldn't be linted because it isn't included in `tsconfig.json`. - -See our docs on [type aware linting](../getting-started/Typed_Linting.mdx) for more information. - -## I get errors telling me "The file must be included in at least one of the projects provided" - -You're using an outdated version of `@typescript-eslint/parser`. -Update to the latest version to see a more informative version of this error message, explained [above](#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file 'backlink to I get errors telling me ESLint was configured to run ...'). - -## How do I turn on a `@typescript-eslint` rule? - -First make sure you've read the docs and understand ESLint configuration files: - -- [Read our getting started guide](../getting-started/Quickstart.mdx) to ensure your config is properly setup to start configuring our rules. -- [Checkout ESLint's documentation on configuring rules](https://eslint.org/docs/latest/use/configure/rules) to ensure you understand how to configure rules. - -Our [rule docs](/rules) detail the options each rule supports under the "Options" heading. -We use TypeScript types to describe an `Options` tuple type for the rule which you can use to configure the a rule. -In your config file the keys of the `rules` object are the names of the rules you wish to configure and the values follow the following form: - -```ts -type Severity = 'off' | 'warn' | 'error'; -type RuleConfig = - | Severity - | [Severity] - | [ - Severity, - // Options is the tuple type from the rule docs - ...Options, - ]; -``` - -Some examples - - - - -```js title="eslint.config.js" -export default tseslint.config( - // ... the rest of your config ... - { - rules: { - // turns a rule on with no configuration (i.e. uses the default configuration) - '@typescript-eslint/array-type': 'error', - // turns on a rule with configuration - '@typescript-eslint/no-explicit-any': ['warn', { ignoreRestArgs: true }], - }, - }, -); -``` - - - - -```js title=".eslintrc.cjs" -module.exports = { - // ... the rest of your config ... - rules: { - // turns a rule on with no configuration (i.e. uses the default configuration) - '@typescript-eslint/array-type': 'error', - // turns on a rule with configuration - '@typescript-eslint/no-explicit-any': ['warn', { ignoreRestArgs: true }], - }, -}; -``` - - - - -## typescript-eslint thinks my variable is never nullish / is `any` / etc., but that is clearly not the case to me - -Our type-aware rules almost always trust the type information provided by the TypeScript compiler. Therefore, an easy way to check if our rule is behaving correctly is to inspect the type of the variable in question, such as by hovering over it in your IDE. - -If the IDE also shows that the type is never nullish / is `any`, you need to fix the type. A very common case is with the [`no-unnecessary-condition`](/rules/no-unnecessary-condition) rule. Take this code for example: - -```ts -let condition = false; - -const f = () => (condition = true); -f(); - -if (condition) { - //^^^^^^^^^ Unnecessary conditional, value is always falsy. -} -``` - -You can see that the type of `condition` is actually the literal type `false` by hovering over it in your IDE. In this case, typescript-eslint cannot possible know better than TypeScript itself, so you need to fix the report by fixing the type, such as through an assertion (`let condition = false as boolean`). - -If the IDE provides different type information from typescript-eslint's report, then make sure that the TypeScript setup used for your IDE, typescript-eslint, and `tsc` are the same: the same TypeScript version, the same type-checking compiler options, and the same files being included in the project. For example, if a type is declared in another file but that file is not included, the type will become `any`, and cause our `no-unsafe-*` rules to report. - -## Can I use ESLint's `--cache` with typescript-eslint? - -[ESLint's `--cache` option](https://eslint.org/docs/latest/use/command-line-interface#caching) caches on a per-file basis. -You can use it, but it will only work reliably for untyped rules -- and even then, not always. - -Any ESLint rule that checks logic across files, including many rules from `eslint-plugin-import`, creates cross-file dependencies. -[Typed lint rules](../getting-started/Typed_Linting.mdx) almost always have dependencies on types across files in practice. -ESLint's caching doesn't account for those cross-file dependencies. - -We don't recommend using `--cache`. - -## I use a framework (like Vue) that requires custom file extensions, and I get errors like "You should add `parserOptions.extraFileExtensions` to your config" - -You can use `parserOptions.extraFileExtensions` to specify an array of non-TypeScript extensions to allow, for example: - - - - -```js title="eslint.config.js" -export default tseslint.config( - // ... the rest of your config ... - { - languageOptions: { - parserOptions: { - tsconfigRootDir: import.meta.dirname, - project: ['./tsconfig.json'], - // Add this line - extraFileExtensions: ['.vue'], - }, - }, - }, -); -``` - - - - -```js title=".eslintrc.js" -module.exports = { - // ... the rest of your config ... - parserOptions: { - tsconfigRootDir: __dirname, - project: ['./tsconfig.json'], - // Add this line - extraFileExtensions: ['.vue'], - }, -}; -``` - - - - -## I am running into errors when parsing TypeScript in my .vue files - -If you are running into issues parsing .vue files, it might be because parsers like [`vue-eslint-parser`](https://www.npmjs.com/package/vue-eslint-parser) are required to parse `.vue` files. In this case you can move `@typescript-eslint/parser` inside `parserOptions` and use `vue-eslint-parser` as the top level parser. - - - - -```js title="eslint.config.js" -import tseslint from 'typescript-eslint'; -// Add this line -import vueParser from 'vue-eslint-parser'; - -export default tseslint.config( - // ... the rest of your config ... - { - languageOptions: { - // Remove this line - parser: tseslint.parser, - // Add this line - parser: vueParser, - parserOptions: { - // Add this line - parser: tseslint.parser, - sourceType: 'module', - }, - }, - }, -); -``` - - - - -```js title=".eslintrc.js" -module.exports = { - // ... the rest of your config ... - // Remove this line - parser: '@typescript-eslint/parser', - // Add this line - parser: 'vue-eslint-parser', - parserOptions: { - parser: '@typescript-eslint/parser', - // Add this line - extraFileExtensions: ['.vue'], - }, -}; -``` - - - - -The `parserOptions.parser` option can also specify an object to specify multiple parsers. See the [`vue-eslint-parser` usage guide](https://eslint.vuejs.org/user-guide/#usage) for more details. - -## One of my lint rules isn't working correctly on a pure JavaScript file - -This is to be expected - ESLint rules do not check file extensions on purpose, as it causes issues in environments that use non-standard extensions (for example, a `.vue` and a `.md` file can both contain TypeScript code to be linted). - -If you have some pure JavaScript code that you do not want to apply certain lint rules to, then you can use [ESLint's `overrides` configuration](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns) to turn off certain rules, or even change the parser based on glob patterns. - -## Should I run ESLint on transpiled output JavaScript files? - -No. - -Source TypeScript files have all the content of output JavaScript files, plus type annotations. -There's no benefit to also linting output JavaScript files. - -## TypeScript should be installed locally - -Make sure that you have installed TypeScript locally i.e. by using `npm install typescript`, not `npm install -g typescript`, -or by using `yarn add typescript`, not `yarn global add typescript`. -See [#2041](https://github.com/typescript-eslint/typescript-eslint/issues/2041) for more information. - -## How can I ban ``? - -ESLint core contains the rule [`no-restricted-syntax`](https://eslint.org/docs/rules/no-restricted-syntax). -This generic rule allows you to specify a [selector](https://eslint.org/docs/developer-guide/selectors) for the code you want to ban, along with a custom error message. - -You can use an AST visualization tool such as [typescript-eslint playground](/play#showAST=es) > _Options_ > _AST Explorer_ on its left sidebar by selecting _ESTree_ to help in figuring out the structure of the AST that you want to ban. - -For example, you can ban enums (or some variation of) using one of the following configs: - -```jsonc -{ - "rules": { - "no-restricted-syntax": [ - "error", - // ban all enums - { - "selector": "TSEnumDeclaration", - "message": "My reason for not using any enums at all", - }, - - // ban just const enums - { - "selector": "TSEnumDeclaration[const=true]", - "message": "My reason for not using const enums", - }, - - // ban just non-const enums - { - "selector": "TSEnumDeclaration:not([const=true])", - "message": "My reason for not using non-const enums", - }, - ], - }, -} -``` - -## Why don't I see TypeScript errors in my ESLint output? - -TypeScript's compiler (or whatever your build chain may be) is specifically designed and built to validate the correctness of your codebase. -Our tooling does not reproduce the errors that TypeScript provides, because doing so would slow down the lint run [1], and duplicate the errors that TypeScript already outputs for you. - -Instead, our tooling exists to **_augment_** TypeScript's built in checks with lint rules that consume the type information in new ways beyond just verifying the runtime correctness of your code. - -[1] - TypeScript computes type information lazily, so us asking for the errors it would produce from the compiler would take an _additional_ ~100ms per file. -This doesn't sound like a lot, but depending on the size of your codebase, it can easily add up to between several seconds to several minutes to a lint run. - -## I get errors from the `no-undef` rule about global variables not being defined, even though there are no TypeScript errors - -The `no-undef` lint rule does not use TypeScript to determine the global variables that exist - instead, it relies upon ESLint's configuration. - -We strongly recommend that you do not use the `no-undef` lint rule on TypeScript projects. -The checks it provides are already provided by TypeScript without the need for configuration - TypeScript just does this significantly better. - -As of our v4.0.0 release, this also applies to types. -If you use global types from a 3rd party package (i.e. anything from an `@types` package), then you will have to configure ESLint appropriately to define these global types. -For example; the `JSX` namespace from `@types/react` is a global 3rd party type that you must define in your ESLint config. - -Note, that for a mixed project including JavaScript and TypeScript, the `no-undef` rule (like any rule) can be turned off for TypeScript files alone as follows: - - - - -```js title="eslint.config.js" -import tseslint from 'typescript-eslint'; - -export default tseslint.config( - // ... the rest of your config ... - { - files: ['**/*.{ts,tsx,mts,cts}'], - rules: { - 'no-undef': 'off', - }, - }, -); -``` - - - - -```js title=".eslintrc.js" -module.exports = { - // ... the rest of your config ... - overrides: [ - { - files: ['*.ts', '*.mts', '*.cts', '*.tsx'], - rules: { - 'no-undef': 'off', - }, - }, - ], -}; -``` - - - - -If you choose to leave on the ESLint `no-undef` lint rule, you can [manually define the set of allowed `globals` in your ESLint config](https://eslint.org/docs/user-guide/configuring/language-options#specifying-globals), and/or you can use one of the [pre-defined environment (`env`) configurations](https://eslint.org/docs/user-guide/configuring/language-options#specifying-environments). - -## How do I check to see what versions are installed? - -If you have multiple versions of our tooling, it can cause various bugs for you. -This is because ESLint may load a different version each run depending on how you run it - leading to inconsistent lint results. - -Installing our tooling in the root of your project does not mean that only one version is installed. -One or more of your dependencies may have its own dependency on our tooling, meaning `npm`/`yarn` will additionally install that version for use by that package. -For example, `react-scripts` (part of `create-react-app`) has a dependency on our tooling. - -You can check what versions are installed in your project using the following commands: - -```bash npm2yarn -npm list @typescript-eslint/eslint-plugin @typescript-eslint/parser -``` - -If you see more than one version installed, then you will have to either use [yarn resolutions](https://classic.yarnpkg.com/en/docs/selective-version-resolutions) to force a single version, or you will have to downgrade your root versions to match the dependency versions. - -**The best course of action in this case is to wait until your dependency releases a new version with support for our latest versions.** - -## How can I specify a TypeScript version / `parserOptions.typescriptLocation`? - -You can't, and you don't want to. - -You should use the same version of TypeScript for linting as the rest of your project. -TypeScript versions often have slight differences in edge cases that can cause contradictory information between typescript-eslint rules and editor information. -For example: - -- `@typescript-eslint/strict-boolean-expressions` might be operating with TypeScript version _X_ and think a variable is `string[] | undefined` -- TypeScript itself might be on version _X+1-beta_ and think the variable is `string[]` - -See [this issue comment](https://github.com/typescript-eslint/typescript-eslint/issues/4102#issuecomment-963265514) for more details. - -## Changes to one file are not reflected when linting other files in my IDE - -> tl;dr: Restart your ESLint server to force an update. - -ESLint currently does not have any way of telling parsers such as ours when an arbitrary file is changed on disk. -That means if you change file A that is imported by file B, it won't update lint caches for file B -- even if file B's text contents have changed. -Sometimes the only solution is to restart your ESLint editor extension altogether. - -See [this issue comment](https://github.com/typescript-eslint/typescript-eslint/issues/5845#issuecomment-1283248238 'GitHub issue 5845, comment 1283248238: details on ESLint cross-file caching') for more information. - -:::tip -[VS Code's ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) provides an `ESLint: Restart ESLint Server` action. -::: - -### I get `no-unsafe-*` complaints for cross-file changes - -See [Changes to one file are not reflected in linting other files in my IDE](#changes-to-one-file-are-not-reflected-when-linting-other-files-in-my-ide). -Rules such as [`no-unsafe-argument`](/rules/no-unsafe-argument), [`no-unsafe-assignment`](/rules/no-unsafe-assignment), and [`no-unsafe-call`](/rules/no-unsafe-call) are often impacted. - -## "The '``' property is deprecated on '``' nodes. Use '``' instead." warnings - -If you're seeing this warning, it's likely you're using an ESLint plugin (or other tooling) that hasn't been updated for typescript-eslint v6. -Make sure you're using the latest versions of each of your ESLint plugins (and other tooling). - -If you've using many ESLint plugins, have updated each to their latest version, and you're not sure which one this complaint is coming from, try either or both of: - -- Running with [`--trace-deprecation`](https://nodejs.org/api/cli.html#--trace-deprecation) (e.g. `npx cross-env NODE_OPTIONS=--trace-deprecation npm run lint`) -- Disabling half of them at a time to narrow down which plugin it is - -Then make sure each of those plugins has a GitHub issue asking that they release a version supporting typescript-eslint v6. - -:::tip -For developers updating ESLint rules in plugins that still need to support typescript-eslint v5: you may need to `||` fall back to the old property key if the new one doesn't exist: - -```diff -- node.typeParameters -+ node.typeArguments || node.typeParameters -``` - -::: - -For more context, see the [Some properties named typeParameters instead of typeArguments](https://github.com/typescript-eslint/typescript-eslint/issues/146) issue, and the implementing [fix: rename typeParameters to typeArguments where needed](https://github.com/typescript-eslint/typescript-eslint/pull/5384) pull request. - -The [typescript-eslint v6 release post](/blog/announcing-typescript-eslint-v6-beta) has more information on typescript-eslint v6. - -## My linting feels really slow - -If you think you're having issues with performance, see our [Performance Troubleshooting documentation](../troubleshooting/Performance.mdx). - -## Are TypeScript project references supported? - -Yes, but only with [`EXPERIMENTAL_useProjectService`](../packages/Parser.mdx#experimental_useprojectservice). - -See [issue #2094 discussing project references](https://github.com/typescript-eslint/typescript-eslint/issues/2094) for more details. diff --git a/docs/troubleshooting/faqs/ESLint.mdx b/docs/troubleshooting/faqs/ESLint.mdx new file mode 100644 index 000000000000..a0e429e61031 --- /dev/null +++ b/docs/troubleshooting/faqs/ESLint.mdx @@ -0,0 +1,96 @@ +--- +id: eslint +sidebar_label: ESLint +title: ESLint FAQs +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Why is a rule from ESLint core not working correctly with TypeScript code? + +This happens because TypeScript adds new features that ESLint doesn't know about. + +The first step is to [check our list of "extension" rules here](/rules/#extension-rules). +An extension rule is a rule which extends the base ESLint rules to support TypeScript syntax. +If you find it in there, give it a go to see if it works for you. +You can configure it by disabling the base rule, and turning on the extension rule. +Here's an example with the `semi` rule: + +```json +{ + "rules": { + "semi": "off", + "@typescript-eslint/semi": "error" + } +} +``` + +If you don't find an existing extension rule, or the extension rule doesn't work for your case, then you can go ahead and check our issues. +[The contributing guide outlines the best way to raise an issue](../../contributing/Issues.mdx). + +> We release a new version our tooling every week. +> _Please_ ensure that you [check our the latest list of "extension" rules](/rules/#extension-rules) **_before_** filing an issue. + +## I get errors from the `no-undef` rule about global variables not being defined, even though there are no TypeScript errors + +The `no-undef` lint rule does not use TypeScript to determine the global variables that exist - instead, it relies upon ESLint's configuration. + +We strongly recommend that you do not use the `no-undef` lint rule on TypeScript projects. +The checks it provides are already provided by TypeScript without the need for configuration - TypeScript just does this significantly better. + +As of our v4.0.0 release, this also applies to types. +If you use global types from a 3rd party package (i.e. anything from an `@types` package), then you will have to configure ESLint appropriately to define these global types. +For example; the `JSX` namespace from `@types/react` is a global 3rd party type that you must define in your ESLint config. + +Note, that for a mixed project including JavaScript and TypeScript, the `no-undef` rule (like any rule) can be turned off for TypeScript files alone as follows: + + + + +```js title="eslint.config.js" +import tseslint from 'typescript-eslint'; + +export default tseslint.config( + // ... the rest of your config ... + { + files: ['**/*.{ts,tsx,mts,cts}'], + rules: { + 'no-undef': 'off', + }, + }, +); +``` + + + + +```js title=".eslintrc.js" +module.exports = { + // ... the rest of your config ... + overrides: [ + { + files: ['*.ts', '*.mts', '*.cts', '*.tsx'], + rules: { + 'no-undef': 'off', + }, + }, + ], +}; +``` + + + + +If you choose to leave on the ESLint `no-undef` lint rule, you can [manually define the set of allowed `globals` in your ESLint config](https://eslint.org/docs/user-guide/configuring/language-options#specifying-globals), and/or you can use one of the [pre-defined environment (`env`) configurations](https://eslint.org/docs/user-guide/configuring/language-options#specifying-environments). + +## Can I use ESLint's `--cache` with typescript-eslint? + +[ESLint's `--cache` option](https://eslint.org/docs/latest/use/command-line-interface#caching) caches on a per-file basis. +You can use it, but it will only work reliably for untyped rules -- and even then, not always. + +Any ESLint rule that checks logic across files, including many rules from `eslint-plugin-import`, creates cross-file dependencies. +[Typed lint rules](../../getting-started/Typed_Linting.mdx) almost always have dependencies on types across files in practice. +ESLint's caching doesn't account for those cross-file dependencies. + +We don't recommend using `--cache`. diff --git a/docs/troubleshooting/faqs/Frameworks.mdx b/docs/troubleshooting/faqs/Frameworks.mdx new file mode 100644 index 000000000000..61dfc3592f73 --- /dev/null +++ b/docs/troubleshooting/faqs/Frameworks.mdx @@ -0,0 +1,102 @@ +--- +id: frameworks +sidebar_label: Frameworks +title: Framework FAQs +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## I use a framework (like Vue) that requires custom file extensions, and I get errors like "You should add `parserOptions.extraFileExtensions` to your config" + +You can use `parserOptions.extraFileExtensions` to specify an array of non-TypeScript extensions to allow, for example: + + + + +```js title="eslint.config.js" +export default tseslint.config( + // ... the rest of your config ... + { + languageOptions: { + parserOptions: { + tsconfigRootDir: import.meta.dirname, + project: ['./tsconfig.json'], + // Add this line + extraFileExtensions: ['.vue'], + }, + }, + }, +); +``` + + + + +```js title=".eslintrc.js" +module.exports = { + // ... the rest of your config ... + parserOptions: { + tsconfigRootDir: __dirname, + project: ['./tsconfig.json'], + // Add this line + extraFileExtensions: ['.vue'], + }, +}; +``` + + + + +## I am running into errors when parsing TypeScript in my .vue files + +If you are running into issues parsing .vue files, it might be because parsers like [`vue-eslint-parser`](https://www.npmjs.com/package/vue-eslint-parser) are required to parse `.vue` files. In this case you can move `@typescript-eslint/parser` inside `parserOptions` and use `vue-eslint-parser` as the top level parser. + + + + +```js title="eslint.config.js" +import tseslint from 'typescript-eslint'; +// Add this line +import vueParser from 'vue-eslint-parser'; + +export default tseslint.config( + // ... the rest of your config ... + { + languageOptions: { + // Remove this line + parser: tseslint.parser, + // Add this line + parser: vueParser, + parserOptions: { + // Add this line + parser: tseslint.parser, + sourceType: 'module', + }, + }, + }, +); +``` + + + + +```js title=".eslintrc.js" +module.exports = { + // ... the rest of your config ... + // Remove this line + parser: '@typescript-eslint/parser', + // Add this line + parser: 'vue-eslint-parser', + parserOptions: { + parser: '@typescript-eslint/parser', + // Add this line + extraFileExtensions: ['.vue'], + }, +}; +``` + + + + +The `parserOptions.parser` option can also specify an object to specify multiple parsers. See the [`vue-eslint-parser` usage guide](https://eslint.vuejs.org/user-guide/#usage) for more details. diff --git a/docs/troubleshooting/faqs/General.mdx b/docs/troubleshooting/faqs/General.mdx new file mode 100644 index 000000000000..addc2ce6b213 --- /dev/null +++ b/docs/troubleshooting/faqs/General.mdx @@ -0,0 +1,171 @@ +--- +id: general +title: General +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## How do I turn on a `@typescript-eslint` rule? + +First make sure you've read the docs and understand ESLint configuration files: + +- [Read our getting started guide](../../getting-started/Quickstart.mdx) to ensure your config is properly setup to start configuring our rules. +- [Checkout ESLint's documentation on configuring rules](https://eslint.org/docs/latest/use/configure/rules) to ensure you understand how to configure rules. + +Our [rule docs](/rules) detail the options each rule supports under the "Options" heading. +We use TypeScript types to describe an `Options` tuple type for the rule which you can use to configure the a rule. +In your config file the keys of the `rules` object are the names of the rules you wish to configure and the values follow the following form: + +```ts +type Severity = 'off' | 'warn' | 'error'; +type RuleConfig = + | Severity + | [Severity] + | [ + Severity, + // Options is the tuple type from the rule docs + ...Options, + ]; +``` + +Some examples + + + + +```js title="eslint.config.js" +export default tseslint.config( + // ... the rest of your config ... + { + rules: { + // turns a rule on with no configuration (i.e. uses the default configuration) + '@typescript-eslint/array-type': 'error', + // turns on a rule with configuration + '@typescript-eslint/no-explicit-any': ['warn', { ignoreRestArgs: true }], + }, + }, +); +``` + + + + +```js title=".eslintrc.cjs" +module.exports = { + // ... the rest of your config ... + rules: { + // turns a rule on with no configuration (i.e. uses the default configuration) + '@typescript-eslint/array-type': 'error', + // turns on a rule with configuration + '@typescript-eslint/no-explicit-any': ['warn', { ignoreRestArgs: true }], + }, +}; +``` + + + + +## How can I ban ``? + +ESLint core contains the rule [`no-restricted-syntax`](https://eslint.org/docs/rules/no-restricted-syntax). +This generic rule allows you to specify a [selector](https://eslint.org/docs/developer-guide/selectors) for the code you want to ban, along with a custom error message. + +You can use an AST visualization tool such as [typescript-eslint playground](/play#showAST=es) > _Options_ > _AST Explorer_ on its left sidebar by selecting _ESTree_ to help in figuring out the structure of the AST that you want to ban. + +For example, you can ban enums (or some variation of) using one of the following configs: + +```jsonc +{ + "rules": { + "no-restricted-syntax": [ + "error", + // ban all enums + { + "selector": "TSEnumDeclaration", + "message": "My reason for not using any enums at all", + }, + + // ban just const enums + { + "selector": "TSEnumDeclaration[const=true]", + "message": "My reason for not using const enums", + }, + + // ban just non-const enums + { + "selector": "TSEnumDeclaration:not([const=true])", + "message": "My reason for not using non-const enums", + }, + ], + }, +} +``` + +## How do I check to see what versions are installed? + +If you have multiple versions of our tooling, it can cause various bugs for you. +This is because ESLint may load a different version each run depending on how you run it - leading to inconsistent lint results. + +Installing our tooling in the root of your project does not mean that only one version is installed. +One or more of your dependencies may have its own dependency on our tooling, meaning `npm`/`yarn` will additionally install that version for use by that package. +For example, `react-scripts` (part of `create-react-app`) has a dependency on our tooling. + +You can check what versions are installed in your project using the following commands: + +```bash npm2yarn +npm list @typescript-eslint/eslint-plugin @typescript-eslint/parser +``` + +If you see more than one version installed, then you will have to either use [yarn resolutions](https://classic.yarnpkg.com/en/docs/selective-version-resolutions) to force a single version, or you will have to downgrade your root versions to match the dependency versions. + +**The best course of action in this case is to wait until your dependency releases a new version with support for our latest versions.** + +## Changes to one file are not reflected when linting other files in my IDE + +> tl;dr: Restart your ESLint server to force an update. + +ESLint currently does not have any way of telling parsers such as ours when an arbitrary file is changed on disk. +That means if you change file A that is imported by file B, it won't update lint caches for file B -- even if file B's text contents have changed. +Sometimes the only solution is to restart your ESLint editor extension altogether. + +See [this issue comment](https://github.com/typescript-eslint/typescript-eslint/issues/5845#issuecomment-1283248238 'GitHub issue 5845, comment 1283248238: details on ESLint cross-file caching') for more information. + +:::tip +[VS Code's ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) provides an `ESLint: Restart ESLint Server` action. +::: + +### I get `no-unsafe-*` complaints for cross-file changes + +See [Changes to one file are not reflected in linting other files in my IDE](#changes-to-one-file-are-not-reflected-when-linting-other-files-in-my-ide). +Rules such as [`no-unsafe-argument`](/rules/no-unsafe-argument), [`no-unsafe-assignment`](/rules/no-unsafe-assignment), and [`no-unsafe-call`](/rules/no-unsafe-call) are often impacted. + +## "The '``' property is deprecated on '``' nodes. Use '``' instead." warnings + +If you're seeing this warning, it's likely you're using an ESLint plugin (or other tooling) that hasn't been updated for typescript-eslint v6. +Make sure you're using the latest versions of each of your ESLint plugins (and other tooling). + +If you've using many ESLint plugins, have updated each to their latest version, and you're not sure which one this complaint is coming from, try either or both of: + +- Running with [`--trace-deprecation`](https://nodejs.org/api/cli.html#--trace-deprecation) (e.g. `npx cross-env NODE_OPTIONS=--trace-deprecation npm run lint`) +- Disabling half of them at a time to narrow down which plugin it is + +Then make sure each of those plugins has a GitHub issue asking that they release a version supporting typescript-eslint v6. + +:::tip +For developers updating ESLint rules in plugins that still need to support typescript-eslint v5: you may need to `||` fall back to the old property key if the new one doesn't exist: + +```diff +- node.typeParameters ++ node.typeArguments || node.typeParameters +``` + +::: + +For more context, see the [Some properties named typeParameters instead of typeArguments](https://github.com/typescript-eslint/typescript-eslint/issues/146) issue, and the implementing [fix: rename typeParameters to typeArguments where needed](https://github.com/typescript-eslint/typescript-eslint/pull/5384) pull request. + +The [typescript-eslint v6 release post](/blog/announcing-typescript-eslint-v6-beta) has more information on typescript-eslint v6. + +## My linting feels really slow + +If you think you're having issues with performance, see our [Performance Troubleshooting documentation](../../troubleshooting/typed-linting/Performance.mdx). diff --git a/docs/troubleshooting/faqs/JavaScript.mdx b/docs/troubleshooting/faqs/JavaScript.mdx new file mode 100644 index 000000000000..ac445281df3f --- /dev/null +++ b/docs/troubleshooting/faqs/JavaScript.mdx @@ -0,0 +1,21 @@ +--- +id: javascript +sidebar_label: JavaScript +title: JavaScript FAQs +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## One of my lint rules isn't working correctly on a pure JavaScript file + +This is to be expected - ESLint rules do not check file extensions on purpose, as it causes issues in environments that use non-standard extensions (for example, a `.vue` and a `.md` file can both contain TypeScript code to be linted). + +If you have some pure JavaScript code that you do not want to apply certain lint rules to, then you can use [ESLint's `overrides` configuration](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns) to turn off certain rules, or even change the parser based on glob patterns. + +## Should I run ESLint on transpiled output JavaScript files? + +No. + +Source TypeScript files have all the content of output JavaScript files, plus type annotations. +There's no benefit to also linting output JavaScript files. diff --git a/docs/troubleshooting/faqs/TypeScript.mdx b/docs/troubleshooting/faqs/TypeScript.mdx new file mode 100644 index 000000000000..e8640cafa98f --- /dev/null +++ b/docs/troubleshooting/faqs/TypeScript.mdx @@ -0,0 +1,37 @@ +--- +id: typescript +sidebar_label: TypeScript +title: TypeScript FAQs +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Should TypeScript should be installed globally or locally? + +Make sure that you have installed TypeScript locally i.e. by using `npm install typescript`, not `npm install -g typescript`, +or by using `yarn add typescript`, not `yarn global add typescript`. +See [#2041](https://github.com/typescript-eslint/typescript-eslint/issues/2041) for more information. + +## Why don't I see TypeScript errors in my ESLint output? + +TypeScript's compiler (or whatever your build chain may be) is specifically designed and built to validate the correctness of your codebase. +Our tooling does not reproduce the errors that TypeScript provides, because doing so would slow down the lint run [1], and duplicate the errors that TypeScript already outputs for you. + +Instead, our tooling exists to **_augment_** TypeScript's built in checks with lint rules that consume the type information in new ways beyond just verifying the runtime correctness of your code. + +[1] - TypeScript computes type information lazily, so us asking for the errors it would produce from the compiler would take an _additional_ ~100ms per file. +This doesn't sound like a lot, but depending on the size of your codebase, it can easily add up to between several seconds to several minutes to a lint run. + +## How can I specify a TypeScript version / `parserOptions.typescriptLocation`? + +You can't, and you don't want to. + +You should use the same version of TypeScript for linting as the rest of your project. +TypeScript versions often have slight differences in edge cases that can cause contradictory information between typescript-eslint rules and editor information. +For example: + +- `@typescript-eslint/strict-boolean-expressions` might be operating with TypeScript version _X_ and think a variable is `string[] | undefined` +- TypeScript itself might be on version _X+1-beta_ and think the variable is `string[]` + +See [this issue comment](https://github.com/typescript-eslint/typescript-eslint/issues/4102#issuecomment-963265514) for more details. diff --git a/docs/getting-started/typed-linting/Monorepos.mdx b/docs/troubleshooting/typed-linting/Monorepos.mdx similarity index 90% rename from docs/getting-started/typed-linting/Monorepos.mdx rename to docs/troubleshooting/typed-linting/Monorepos.mdx index a8c45997d882..5a567b044aef 100644 --- a/docs/getting-started/typed-linting/Monorepos.mdx +++ b/docs/troubleshooting/typed-linting/Monorepos.mdx @@ -1,16 +1,20 @@ --- id: monorepos +slug: /troubleshooting/typed-linting/monorepos title: Monorepo Configuration -pagination_next: null --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -If you're using a monorepo, these docs will help you figure out how to setup typed linting. +If you're using a monorepo with `parserOptions.project`, these docs will help you figure out how to setup typed linting. If you don't want to use typed linting, then you can stop here - you don't need to do anything special. -Configurations will look different based on which setup you use: +:::tip +The [new "project service" (`parserOptions.projectService`) in v8](/blog/announcing-typescript-eslint-v8-beta#project-service) requires no additional configuration for monorepos. +::: + +`parserOptions.project` configurations will look different based on which monorepo setup you use: 1. [One root `tsconfig.json`](#one-root-tsconfigjson) 2. [One `tsconfig.json` per package (and an optional one in the root)](#one-tsconfigjson-per-package-and-an-optional-one-in-the-root) @@ -42,7 +46,7 @@ Be sure to update your ESLint configuration file to point at this new TSConfig. ## One `tsconfig.json` per package (and an optional one in the root) -The `parserOptions.project` option introduced in [Linting with Type Information](../Typed_Linting.mdx) accepts an array of relative paths. +The `parserOptions.project` option introduced in [Linting with Type Information](../typed-linting/index.mdx) accepts an array of relative paths. Paths may be provided as [Node globs](https://github.com/isaacs/node-glob/blob/f5a57d3d6e19b324522a3fa5bdd5075fd1aa79d1/README.md#glob-primer). For each file being linted, the first matching project path will be used as its backing TSConfig. @@ -160,7 +164,3 @@ As an interim workaround, consider one of the following: - Switching to one root `tsconfig.eslint.json` (see [One root `tsconfig.json`](#one-root-tsconfigjson)) - Using a shell script to only lint one package at a time, using your existing config above. - -## Troubleshooting - -If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](../../troubleshooting/FAQ.mdx). diff --git a/docs/troubleshooting/Performance.mdx b/docs/troubleshooting/typed-linting/Performance.mdx similarity index 95% rename from docs/troubleshooting/Performance.mdx rename to docs/troubleshooting/typed-linting/Performance.mdx index 71a63da234b2..ba5037b1d628 100644 --- a/docs/troubleshooting/Performance.mdx +++ b/docs/troubleshooting/typed-linting/Performance.mdx @@ -1,12 +1,13 @@ --- -id: performance-troubleshooting -title: Performance Troubleshooting +id: performance +slug: /troubleshooting/typed-linting/performance +title: Performance --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -As mentioned in the [type-aware linting doc](../getting-started/Typed_Linting.mdx), if you're using type-aware linting, your lint times should be roughly the same as your build times. +As mentioned in the [type-aware linting doc](../../getting-started/Typed_Linting.mdx), if you're using type-aware linting, your lint times should be roughly the same as your build times. If you're experiencing times much slower than that, then there are a few common culprits. @@ -87,7 +88,7 @@ Across a large codebase, these can add up, and severely impact performance. We recommend not using this rule, and instead using a tool like [`prettier`](https://www.npmjs.com/package/prettier) to enforce a standardized formatting. -See our [documentation on formatting](./Formatting.mdx) for more information. +See our [documentation on formatting](../../users/What_About_Formatting.mdx) for more information. ## `eslint-plugin-prettier` diff --git a/docs/troubleshooting/typed-linting/index.mdx b/docs/troubleshooting/typed-linting/index.mdx new file mode 100644 index 000000000000..6723ae5aea34 --- /dev/null +++ b/docs/troubleshooting/typed-linting/index.mdx @@ -0,0 +1,184 @@ +--- +id: index +title: Typed Linting +slug: /troubleshooting/typed-linting +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +## I get errors telling me "Having many files run with the default project is known to cause performance issues and slow down linting." + +These errors are caused by using the [`EXPERIMENTAL_useProjectService`](../../packages/Parser.mdx#experimental_useprojectservice) `allowDefaultProjectForFiles` with an excessively wide glob. +`allowDefaultProjectForFiles` causes a new TypeScript "program" to be built for each "out of project" file it includes, which incurs a performance overhead for each file. + +To resolve this error, narrow the glob(s) used for `allowDefaultProjectForFiles` to include fewer files. +For example: + +```diff title="eslint.config.js" +parserOptions: { + EXPERIMENTAL_useProjectService: { + allowDefaultProjectForFiles: [ +- "**/*.js", ++ "./*.js" + ] + } +} +``` + +You may also need to include more files in your `tsconfig.json`. +For example: + +```diff title="tsconfig.json" +"include": [ + "src", ++ "*.js" +] +``` + +If you cannot do this, please [file an issue on typescript-eslint's typescript-estree package](https://github.com/typescript-eslint/typescript-eslint/issues/new?assignees=&labels=enhancement%2Ctriage&projects=&template=07-enhancement-other.yaml&title=Enhancement%3A+%3Ca+short+description+of+my+proposal%3E) telling us your use case and why you need more out-of-project files linted. +Be sure to include a minimal reproduction we can work with to understand your use case! + +## I get errors telling me "ESLint was configured to run ... However, that TSConfig does not / none of those TSConfigs include this file" + +These errors are caused by an ESLint config requesting type information be generated for a file that isn't included in the TypeScript configuration. + +### Fixing the Error + + + +- If you **do not** want to lint the file: + - Use [one of the options ESLint offers](https://eslint.org/docs/latest/user-guide/configuring/ignoring-code) to ignore files, namely a `.eslintignore` file, or `ignorePatterns` config. +- If you **do** want to lint the file: + - If you **do not** want to lint the file with [type-aware linting](../../getting-started/Typed_Linting.mdx): + - Use [ESLint's `overrides` configuration](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#configuration-based-on-glob-patterns) with our [`disable-type-checked`](../../users/Shared_Configurations.mdx#disable-type-checked) config to disable type checking for just that type of file. + + + + ```js title="eslint.config.js" + import tseslint from 'typescript-eslint'; + + export default tseslint.config( + // ... the rest of your config ... + { + files: ['**/*.js'], + extends: [tseslint.configs.disableTypeChecked], + }, + ); + ``` + + + + + ```js title=".eslintrc.cjs" + module.exports = { + // ... the rest of your config ... + overrides: [ + { + extends: ['plugin:@typescript-eslint/disable-type-checked'], + files: ['./**/*.js'], + }, + ], + }; + ``` + + + + - Alternatively to disable type checking for files manually, you can set `parserOptions: { project: false }` to an override for the files you wish to exclude. + - If you **do** want to lint the file with [type-aware linting](../../getting-started/Typed_Linting.mdx): + - Check the `include` option of each of the TSConfigs that you provide to `parserOptions.project` - you must ensure that all files match an `include` glob, or else our tooling will not be able to find it. + - If the file is a `.cjs`, `.js`, or `.mjs` file, make sure [`allowJs`](https://www.typescriptlang.org/tsconfig#allowJs) is enabled. + - If your file shouldn't be a part of one of your existing tsconfigs (for example, it is a script/tool local to the repo), then consider creating a new tsconfig (we advise calling it `tsconfig.eslint.json`) in your project root which lists this file in its `include`. For an example of this, you can check out the configuration we use in this repo: + - [`tsconfig.eslint.json`](https://github.com/typescript-eslint/typescript-eslint/blob/main/tsconfig.eslint.json) + - [`eslint.config.mjs`](https://github.com/typescript-eslint/typescript-eslint/blob/main/eslint.config.mjs) + + + +### More Details + +This error may appear from the combination of two things: + +- The ESLint configuration for the source file specifies at least one TSConfig file in `parserOptions.project` +- None of those TSConfig files includes the source file being linted + - Note that files with the same name and different extension may not be recognized by TypeScript: see [`parserOptions.project` docs](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsproject) + +When TSConfig files are specified for parsing a source file, `@typescript-eslint/parser` will use the first TSConfig that is able to include that source file (per [aka.ms/tsconfig#include](https://www.typescriptlang.org/tsconfig#include)) to generate type information. +However, if no specified TSConfig includes the source file, the parser won't be able to generate type information. + +This error most commonly happens on config files or similar that are not included in their project TSConfig(s). +For example, many projects have files like: + +- An `.eslintrc.cjs` / `eslint.config.js` with `parserOptions.project: ["./tsconfig.json"]` +- A `tsconfig.json` with `include: ["src"]` + +In that case, viewing the file in an IDE with the ESLint extension will show the error notice that the file couldn't be linted because it isn't included in `tsconfig.json`. + +See our docs on [type aware linting](../../getting-started/Typed_Linting.mdx) for more information. + +## I get errors telling me "The file must be included in at least one of the projects provided" + +You're using an outdated version of `@typescript-eslint/parser`. +Update to the latest version to see a more informative version of this error message, explained [above](#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file 'backlink to I get errors telling me ESLint was configured to run ...'). + + + +## I get errors telling me "Having many files run with the default project is known to cause performance issues and slow down linting." + +These errors are caused by using the [`EXPERIMENTAL_useProjectService`](../../packages/Parser.mdx#experimental_useprojectservice) `allowDefaultProjectForFiles` with an excessively wide glob. +`allowDefaultProjectForFiles` causes a new TypeScript "program" to be built for each "out of project" file it includes, which incurs a performance overhead for each file. + +To resolve this error, narrow the glob(s) used for `allowDefaultProjectForFiles` to include fewer files. +For example: + +```diff title="eslint.config.js" +parserOptions: { + EXPERIMENTAL_useProjectService: { + allowDefaultProjectForFiles: [ +- "**/*.js", ++ "./*.js" + ] + } +} +``` + +You may also need to include more files in your `tsconfig.json`. +For example: + +```diff title="tsconfig.json" +"include": [ + "src", ++ "*.js" +] +``` + +If you cannot do this, please [file an issue on typescript-eslint's typescript-estree package](https://github.com/typescript-eslint/typescript-eslint/issues/new?assignees=&labels=enhancement%2Ctriage&projects=&template=07-enhancement-other.yaml&title=Enhancement%3A+%3Ca+short+description+of+my+proposal%3E) telling us your use case and why you need more out-of-project files linted. +Be sure to include a minimal reproduction we can work with to understand your use case! + +## typescript-eslint thinks my variable is never nullish / is `any` / etc., but that is clearly not the case to me + +Our type-aware rules almost always trust the type information provided by the TypeScript compiler. Therefore, an easy way to check if our rule is behaving correctly is to inspect the type of the variable in question, such as by hovering over it in your IDE. + +If the IDE also shows that the type is never nullish / is `any`, you need to fix the type. A very common case is with the [`no-unnecessary-condition`](/rules/no-unnecessary-condition) rule. Take this code for example: + +```ts +let condition = false; + +const f = () => (condition = true); +f(); + +if (condition) { + //^^^^^^^^^ Unnecessary conditional, value is always falsy. +} +``` + +You can see that the type of `condition` is actually the literal type `false` by hovering over it in your IDE. In this case, typescript-eslint cannot possible know better than TypeScript itself, so you need to fix the report by fixing the type, such as through an assertion (`let condition = false as boolean`). + +If the IDE provides different type information from typescript-eslint's report, then make sure that the TypeScript setup used for your IDE, typescript-eslint, and `tsc` are the same: the same TypeScript version, the same type-checking compiler options, and the same files being included in the project. For example, if a type is declared in another file but that file is not included, the type will become `any`, and cause our `no-unsafe-*` rules to report. + +## Are TypeScript project references supported? + +Yes, but only with [`EXPERIMENTAL_useProjectService`](../../packages/Parser.mdx#experimental_useprojectservice). + +See [issue #2094 discussing project references](https://github.com/typescript-eslint/typescript-eslint/issues/2094) for more details. diff --git a/docs/users/Shared_Configurations.mdx b/docs/users/Shared_Configurations.mdx index 59c7e26cb66d..9c406d17d0c9 100644 --- a/docs/users/Shared_Configurations.mdx +++ b/docs/users/Shared_Configurations.mdx @@ -473,4 +473,4 @@ If you feel strongly that a specific rule should (or should not) be one of these None of the preset configs provided by typescript-eslint enable formatting rules (rules that only serve to enforce code whitespace and other trivia). We strongly recommend you use Prettier or an equivalent for formatting your code, not ESLint formatting rules. -See [What About Formatting? > Suggested Usage](../troubleshooting/Formatting.mdx#suggested-usage---prettier). +See [What About Formatting? > Suggested Usage](./What_About_Formatting.mdx#suggested-usage---prettier). diff --git a/docs/troubleshooting/Formatting.mdx b/docs/users/What_About_Formatting.mdx similarity index 97% rename from docs/troubleshooting/Formatting.mdx rename to docs/users/What_About_Formatting.mdx index 814544d1daab..75a83c81ff59 100644 --- a/docs/troubleshooting/Formatting.mdx +++ b/docs/users/What_About_Formatting.mdx @@ -1,5 +1,5 @@ --- -id: formatting +id: what-about-formatting title: What About Formatting? --- @@ -94,7 +94,7 @@ Note that even if you use a formatter other than `prettier`, you can use `eslint - The _config_ only disables rules from core and other plugins. - The _plugin_ loads and runs Prettier inside ESLint. -Running Prettier inside ESLint can be slow: see [Performance Troubleshooting > `eslint-plugin-prettier`](./Performance.mdx#eslint-plugin-prettier). +Running Prettier inside ESLint can be slow: see [Performance Troubleshooting > `eslint-plugin-prettier`](../troubleshooting/typed-linting/Performance.mdx#eslint-plugin-prettier). However, because it doesn't re-implement Prettier's logic in ESLint, the caveats mentioned about using linters for formatting don't apply to `eslint-plugin-prettier` either. ## ESLint Core and Formatting diff --git a/docs/troubleshooting/TSLint.mdx b/docs/users/What_About_TSLint.mdx similarity index 97% rename from docs/troubleshooting/TSLint.mdx rename to docs/users/What_About_TSLint.mdx index 1c595ac7c8a8..76b21d55f071 100644 --- a/docs/troubleshooting/TSLint.mdx +++ b/docs/users/What_About_TSLint.mdx @@ -1,7 +1,6 @@ --- -id: tslint +id: what-about-tslint title: What About TSLint? -sidebar_label: What About TSLint? --- TSLint was a linter equivalent to ESLint that was written specifically to work directly on TypeScript code. diff --git a/docs/Users.mdx b/docs/users/index.mdx similarity index 96% rename from docs/Users.mdx rename to docs/users/index.mdx index 120d225240c9..5280ea3cb541 100644 --- a/docs/Users.mdx +++ b/docs/users/index.mdx @@ -1,5 +1,5 @@ --- -id: users +id: index title: Users --- diff --git a/netlify.toml b/netlify.toml index c3bbdc311302..88d725aa954c 100644 --- a/netlify.toml +++ b/netlify.toml @@ -31,9 +31,13 @@ from = "/docs/linting/type-linting" to = "/linting/typed-linting" +[[redirects]] + from = "/linting/troubleshooting" + to = "/troubleshooting/faqs/general" + [[redirects]] from = "/docs/linting/monorepo" - to = "/linting/typed-linting/monorepos" + to = "/linting/troubleshooting/typed-linting/Monorepos" [[redirects]] from = "/docs/linting/tslint" diff --git a/packages/eslint-plugin/docs/rules/README.md b/packages/eslint-plugin/docs/rules/README.md index 32c1cefc16e0..3cdf72e4c923 100644 --- a/packages/eslint-plugin/docs/rules/README.md +++ b/packages/eslint-plugin/docs/rules/README.md @@ -34,7 +34,7 @@ import RulesTable from "@site/src/components/RulesTable"; - `💭 requires type information` refers to whether the rule requires [typed linting](/getting-started/typed-linting). - `🧱 extension rule` means that the rule is an extension of an [core ESLint rule](https://eslint.org/docs/latest/rules) (see [Extension Rules](#extension-rules)). - `📐 formatting rule` means that the rule has to do with formatting. - - We [strongly recommend against using ESLint for formatting](/troubleshooting/formatting). + - We [strongly recommend against using ESLint for formatting](/users/what-about-formatting). - Soon, formatting rules will be moved to the [ESLint stylistic plugin](https://eslint.style). - `💀 deprecated rule` means that the rule should no longer be used and will be removed from the plugin in a future version. diff --git a/packages/eslint-plugin/docs/rules/no-extra-semi.mdx b/packages/eslint-plugin/docs/rules/no-extra-semi.mdx index ec23c28eca8d..d59534dcfc60 100644 --- a/packages/eslint-plugin/docs/rules/no-extra-semi.mdx +++ b/packages/eslint-plugin/docs/rules/no-extra-semi.mdx @@ -12,4 +12,4 @@ import TabItem from '@theme/TabItem'; This rule extends the base [`eslint/no-extra-semi`](https://eslint.org/docs/rules/no-extra-semi) rule. It adds support for class properties. -Note that this rule is classified as a "Suggestion" rule instead of a "Layout & Formatting" rule because [adding extra semi-colons actually changes the AST of the program](https://typescript-eslint.io/play/#ts=5.1.6&showAST=es&fileType=.ts&code=MYewdgzgLgBAHjAvDAjAbg0A&eslintrc=N4KABGBEBOCuA2BTAzpAXGUEKQHYHsBaRADwBdoBDQ5RAWwEt0p8AzVyAGnG0gAEyATwAOKAMbQGwssWTwGuMgHoCxclRr0mGSImjR80SDwC%2BIE0A&tsconfig=&tokens=false). With that said, modern TypeScript formatters will remove extra semi-colons automatically during the formatting process. Thus, if you [use a formatter](/troubleshooting/formatting), then enabling this rule is probably unnecessary. +Note that this rule is classified as a "Suggestion" rule instead of a "Layout & Formatting" rule because [adding extra semi-colons actually changes the AST of the program](https://typescript-eslint.io/play/#ts=5.1.6&showAST=es&fileType=.ts&code=MYewdgzgLgBAHjAvDAjAbg0A&eslintrc=N4KABGBEBOCuA2BTAzpAXGUEKQHYHsBaRADwBdoBDQ5RAWwEt0p8AzVyAGnG0gAEyATwAOKAMbQGwssWTwGuMgHoCxclRr0mGSImjR80SDwC%2BIE0A&tsconfig=&tokens=false). With that said, modern TypeScript formatters will remove extra semi-colons automatically during the formatting process. Thus, if you [use a formatter](/users/what-about-formatting), then enabling this rule is probably unnecessary. diff --git a/packages/eslint-plugin/docs/rules/no-type-alias.mdx b/packages/eslint-plugin/docs/rules/no-type-alias.mdx index 64822ea75a92..11068fbab2f6 100644 --- a/packages/eslint-plugin/docs/rules/no-type-alias.mdx +++ b/packages/eslint-plugin/docs/rules/no-type-alias.mdx @@ -19,7 +19,7 @@ TypeScript type aliases are a commonly necessary language feature; banning it al :::note If you want to ban certain classifications of type aliases, consider using [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax). -See [Troubleshooting & FAQs](/troubleshooting#how-can-i-ban-specific-language-feature). +See [Troubleshooting & FAQs](/troubleshooting/faqs/general#how-can-i-ban-specific-language-feature). ::: diff --git a/packages/typescript-estree/src/convert.ts b/packages/typescript-estree/src/convert.ts index 08cb7bd0bed3..095188bb15a3 100644 --- a/packages/typescript-estree/src/convert.ts +++ b/packages/typescript-estree/src/convert.ts @@ -3529,7 +3529,7 @@ export class Converter { : (): Properties[typeof valueKey] => { if (!warned) { process.emitWarning( - `The '${aliasKey}' property is deprecated on ${node.type} nodes. Use '${valueKey}' instead. See https://typescript-eslint.io/linting/troubleshooting#the-key-property-is-deprecated-on-type-nodes-use-key-instead-warnings.`, + `The '${aliasKey}' property is deprecated on ${node.type} nodes. Use '${valueKey}' instead. See https://typescript-eslint.io/troubleshooting/faqs/general#the-key-property-is-deprecated-on-type-nodes-use-key-instead-warnings.`, 'DeprecationWarning', ); warned = true; diff --git a/packages/typescript-estree/src/create-program/createProjectProgram.ts b/packages/typescript-estree/src/create-program/createProjectProgram.ts index 3e8432d0b46f..00d9ed67da13 100644 --- a/packages/typescript-estree/src/create-program/createProjectProgram.ts +++ b/packages/typescript-estree/src/create-program/createProjectProgram.ts @@ -103,7 +103,7 @@ function createProjectProgram( `- Change ESLint's list of included files to not include this file`, `- Change ${describedSpecifiers} to include this file`, `- Create a new TSConfig that includes this file and include it in your parserOptions.project`, - `See the typescript-eslint docs for more info: https://typescript-eslint.io/linting/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file`, + `See the typescript-eslint docs for more info: https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file`, ); } diff --git a/packages/typescript-estree/src/create-program/validateDefaultProjectForFilesGlob.ts b/packages/typescript-estree/src/create-program/validateDefaultProjectForFilesGlob.ts index 598982bdc8e3..d2b36760d76b 100644 --- a/packages/typescript-estree/src/create-program/validateDefaultProjectForFilesGlob.ts +++ b/packages/typescript-estree/src/create-program/validateDefaultProjectForFilesGlob.ts @@ -4,7 +4,7 @@ export const DEFAULT_PROJECT_FILES_ERROR_EXPLANATION = ` Having many files run with the default project is known to cause performance issues and slow down linting. -See https://typescript-eslint.io/troubleshooting/#allowdefaultprojectforfiles-glob-too-wide +See https://typescript-eslint.io/troubleshooting/typed-linting#allowdefaultprojectforfiles-glob-too-wide `; export function validateDefaultProjectForFilesGlob( diff --git a/packages/typescript-estree/tests/lib/convert.test.ts b/packages/typescript-estree/tests/lib/convert.test.ts index 9988c969b6a7..87fe09b63367 100644 --- a/packages/typescript-estree/tests/lib/convert.test.ts +++ b/packages/typescript-estree/tests/lib/convert.test.ts @@ -309,7 +309,7 @@ describe('convert', () => { esCallExpression.typeParameters; expect(emitWarning).toHaveBeenCalledWith( - `The 'typeParameters' property is deprecated on CallExpression nodes. Use 'typeArguments' instead. See https://typescript-eslint.io/linting/troubleshooting#the-key-property-is-deprecated-on-type-nodes-use-key-instead-warnings.`, + `The 'typeParameters' property is deprecated on CallExpression nodes. Use 'typeArguments' instead. See https://typescript-eslint.io/troubleshooting/faqs/general#the-key-property-is-deprecated-on-type-nodes-use-key-instead-warnings.`, 'DeprecationWarning', ); }); diff --git a/packages/typescript-estree/tests/lib/parse.test.ts b/packages/typescript-estree/tests/lib/parse.test.ts index f973358d85a1..ad19d4277b5e 100644 --- a/packages/typescript-estree/tests/lib/parse.test.ts +++ b/packages/typescript-estree/tests/lib/parse.test.ts @@ -382,7 +382,7 @@ describe('parseAndGenerateServices', () => { - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project - See the typescript-eslint docs for more info: https://typescript-eslint.io/linting/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" + See the typescript-eslint docs for more info: https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `); expect(testParse('ts/notIncluded02.tsx')) .toThrowErrorMatchingInlineSnapshot(` @@ -391,7 +391,7 @@ describe('parseAndGenerateServices', () => { - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project - See the typescript-eslint docs for more info: https://typescript-eslint.io/linting/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" + See the typescript-eslint docs for more info: https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `); expect(testParse('js/notIncluded01.js')) .toThrowErrorMatchingInlineSnapshot(` @@ -400,7 +400,7 @@ describe('parseAndGenerateServices', () => { - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project - See the typescript-eslint docs for more info: https://typescript-eslint.io/linting/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" + See the typescript-eslint docs for more info: https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `); expect(testParse('js/notIncluded02.jsx')) .toThrowErrorMatchingInlineSnapshot(` @@ -409,7 +409,7 @@ describe('parseAndGenerateServices', () => { - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project - See the typescript-eslint docs for more info: https://typescript-eslint.io/linting/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" + See the typescript-eslint docs for more info: https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `); }); }); @@ -442,7 +442,7 @@ describe('parseAndGenerateServices', () => { - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project - See the typescript-eslint docs for more info: https://typescript-eslint.io/linting/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" + See the typescript-eslint docs for more info: https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `); }); @@ -455,7 +455,7 @@ describe('parseAndGenerateServices', () => { - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project - See the typescript-eslint docs for more info: https://typescript-eslint.io/linting/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" + See the typescript-eslint docs for more info: https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `); }); }); @@ -512,7 +512,7 @@ describe('parseAndGenerateServices', () => { - Change ESLint's list of included files to not include this file - Change one of those TSConfigs to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project - See the typescript-eslint docs for more info: https://typescript-eslint.io/linting/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" + See the typescript-eslint docs for more info: https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `); }); } diff --git a/packages/typescript-estree/tests/lib/useProgramFromProjectService.test.ts b/packages/typescript-estree/tests/lib/useProgramFromProjectService.test.ts index cd2323d34120..d5f49fc69528 100644 --- a/packages/typescript-estree/tests/lib/useProgramFromProjectService.test.ts +++ b/packages/typescript-estree/tests/lib/useProgramFromProjectService.test.ts @@ -142,7 +142,7 @@ describe('useProgramFromProjectService', () => { Having many files run with the default project is known to cause performance issues and slow down linting. -See https://typescript-eslint.io/troubleshooting/#allowdefaultprojectforfiles-glob-too-wide +See https://typescript-eslint.io/troubleshooting/typed-linting#allowdefaultprojectforfiles-glob-too-wide Matching files: - a @@ -176,7 +176,7 @@ If you absolutely need more files included, set parserOptions.EXPERIMENTAL_usePr Having many files run with the default project is known to cause performance issues and slow down linting. -See https://typescript-eslint.io/troubleshooting/#allowdefaultprojectforfiles-glob-too-wide +See https://typescript-eslint.io/troubleshooting/typed-linting#allowdefaultprojectforfiles-glob-too-wide Matching files: - 0 diff --git a/packages/website/blog/2023-09-18-parser-options-project-true.md b/packages/website/blog/2023-09-18-parser-options-project-true.md index e2ffd4ef6d1f..f4926eaca8c8 100644 --- a/packages/website/blog/2023-09-18-parser-options-project-true.md +++ b/packages/website/blog/2023-09-18-parser-options-project-true.md @@ -51,7 +51,7 @@ Explicitly indicating which TSConfig files are used for typed linting can be use Developers like being given explicit control over their tooling. However, we've seen a few issues arise from this approach: -- Particularly large repos can end up with so many TSConfig globs, they become confusing to developers or even cause [performance issues from overly permissive globs](/troubleshooting/performance-troubleshooting#wide-includes-in-your-eslint-options) +- Particularly large repos can end up with so many TSConfig globs, they become confusing to developers or even cause [performance issues from overly permissive globs](/troubleshooting/typed-linting/performance#wide-includes-in-your-eslint-options) - Needing to change a template ESLint config every time it's used for a different repository structure is a pain - Using a TSConfig that's different from what your editor uses can result in different lint reports between the editor and the command-line @@ -135,7 +135,7 @@ Manual Program creation logic comes with a few issues: - For example, [typescript-eslint does not yet support Project References](https://github.com/typescript-eslint/typescript-eslint/issues/2094). - The TypeScript compiler options used in the user's editor might differ from the compiler options in the TSConfigs they specified on disk. - Files not included in created Programs can't be linted with type information, even though editors still typically surface type information when editing those files. - - Most commonly, `.eslintrc.(c)js` files can be tricky to lint, resulting in the dreaded [_TSConfig does not include this file_ error](/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). + - Most commonly, `.eslintrc.(c)js` files can be tricky to lint, resulting in the dreaded [_TSConfig does not include this file_ error](/troubleshooting/typed-linting/performance#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). We're working on an option to instead call the same TypeScript "Project Service" APIs that editors such as VS Code use to create Programs for us instead. Project Services will automatically detect the TSConfig for each file (like `project: true`), and will also allow type information to be computed for JavaScript files without the `allowJs` compiler option (unlike `project: true`). diff --git a/packages/website/blog/2023-12-25-deprecating-formatting-rules.md b/packages/website/blog/2023-12-25-deprecating-formatting-rules.md index c25ddbf6a490..f68ef11eba3a 100644 --- a/packages/website/blog/2023-12-25-deprecating-formatting-rules.md +++ b/packages/website/blog/2023-12-25-deprecating-formatting-rules.md @@ -21,7 +21,7 @@ We'll keep these deprecated rules available until our next major version. ## Context: Formatting Rules The ESLint blog post thoroughly explains the history and tradeoffs of formatting rules. -See also [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies/#what-are-the-changes) and our _[What About Formatting?](/troubleshooting/formatting)_ docs. +See also [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies/#what-are-the-changes) and our _[What About Formatting?](/users/what-about-formatting)_ docs. The performance downsides of formatting rules are heightened when [linting with type information](/getting-started/typed-linting). ## Timelines diff --git a/packages/website/docusaurus.config.mts b/packages/website/docusaurus.config.mts index a728e223b119..369a6fd7210b 100644 --- a/packages/website/docusaurus.config.mts +++ b/packages/website/docusaurus.config.mts @@ -262,33 +262,57 @@ const pluginPwaOptions: PluginPwaOptions = { const redirects: PluginRedirectOptions = { redirects: [ + { + from: '/getting-started/typed-linting/monorepos', + to: '/troubleshooting/typed-linting/monorepos', + }, { from: '/linting/configs', to: '/users/configs', }, { from: '/linting/troubleshooting', - to: '/troubleshooting', + to: '/troubleshooting/faqs/general', }, { from: '/linting/troubleshooting/formatting', - to: '/troubleshooting/formatting', + to: '/users/what-about-formatting', }, { - from: '/linting/troubleshooting/performance-troubleshooting', - to: '/troubleshooting/performance-troubleshooting', + from: '/linting/troubleshooting/typed-linting/Performance-troubleshooting', + to: '/troubleshooting/typed-linting/performance', }, { from: '/linting/troubleshooting/tslint', - to: '/troubleshooting/tslint', + to: '/users/what-about-tslint', }, { from: '/linting/typed-linting', to: '/getting-started/typed-linting', }, { - from: '/linting/typed-linting/monorepos', - to: '/getting-started/typed-linting/monorepos', + from: '/troubleshooting', + to: '/troubleshooting/faqs/general', + }, + { + from: '/troubleshooting/faqs', + to: '/troubleshooting/faqs/general', + }, + { + from: '/troubleshooting/formatting', + to: '/users/what-about-formatting', + }, + { + from: '/troubleshooting/tslint', + to: '/users/what-about-tslint', + }, + { + from: '/troubleshooting/performance-troubleshooting', + to: '/troubleshooting/typed-linting/performance', + }, + { + from: '/linting/troubleshooting/typed-linting/Monorepos', + to: '/troubleshooting/typed-linting/monorepos', }, { from: '/maintenance/issues/rule-deprecations', diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts b/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts index 1b47257bcbcf..7365438bde60 100644 --- a/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts +++ b/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts @@ -49,11 +49,12 @@ export function insertWhenNotToUseIt(page: RuleDocsPage): void { { type: 'link', title: null, - url: `/troubleshooting/performance-troubleshooting`, + url: `/troubleshooting/typed-linting/performance`, children: [ { type: 'text', - value: 'Performance Troubleshooting', + value: + 'Troubleshooting > Linting with Type Information > Performance', }, ], }, diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index 02cbad567249..8655d2c29834 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -5,22 +5,20 @@ module.exports = { { collapsible: false, items: [ - { - label: 'Quickstart', - id: 'getting-started/quickstart', - type: 'doc', - }, { collapsible: false, - items: ['getting-started/typed-linting/monorepos'], - label: 'Linting with Type Information', + items: ['getting-started/legacy-eslint-setup'], + label: 'Quickstart', link: { - id: 'getting-started/typed-linting', + id: 'getting-started/quickstart', type: 'doc', }, type: 'category', }, - 'getting-started/legacy-eslint-setup', + { + id: 'getting-started/typed-linting', + type: 'doc', + }, ], label: 'Getting Started', link: { @@ -29,18 +27,44 @@ module.exports = { }, type: 'category', }, - { collapsible: false, items: [ - 'troubleshooting/faqs', - 'troubleshooting/performance-troubleshooting', - 'troubleshooting/formatting', - 'troubleshooting/tslint', + { + collapsed: true, + collapsible: true, + items: [ + 'troubleshooting/faqs/general', + 'troubleshooting/faqs/eslint', + 'troubleshooting/faqs/frameworks', + 'troubleshooting/faqs/javascript', + 'troubleshooting/faqs/typescript', + ], + label: 'FAQs', + link: { + id: 'troubleshooting/faqs/general', + type: 'doc', + }, + type: 'category', + }, + { + collapsed: true, + collapsible: true, + items: [ + 'troubleshooting/typed-linting/monorepos', + 'troubleshooting/typed-linting/performance', + ], + label: 'Typed Linting', + link: { + id: 'troubleshooting/typed-linting/index', + type: 'doc', + }, + type: 'category', + }, ], label: 'Troubleshooting & FAQs', link: { - id: 'troubleshooting/faqs', + id: 'troubleshooting/faqs/general', type: 'doc', }, type: 'category', @@ -48,19 +72,16 @@ module.exports = { { collapsible: false, items: [ - { - label: 'Rules', - href: '/rules/', - type: 'link', - }, 'users/configs', 'users/dependency-versions', 'users/releases', 'users/versioning', + 'users/what-about-formatting', + 'users/what-about-tslint', ], label: 'Users', link: { - id: 'users', + id: 'users/index', type: 'doc', }, type: 'category',