From 76cb7f59960c6cfdf333643853dd60d2e781dc03 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 18 Jul 2024 11:21:15 -0400 Subject: [PATCH] docs: clarify projectService out-of-project remediation steps --- docs/packages/Parser.mdx | 2 +- docs/troubleshooting/typed-linting/index.mdx | 140 +++++++------------ 2 files changed, 53 insertions(+), 89 deletions(-) diff --git a/docs/packages/Parser.mdx b/docs/packages/Parser.mdx index 3e146d89ad26..a0f72912372b 100644 --- a/docs/packages/Parser.mdx +++ b/docs/packages/Parser.mdx @@ -326,7 +326,7 @@ This option brings two main benefits over the older `project`: For more information, see: - [feat(typescript-estree): add EXPERIMENTAL_useProjectService option to use TypeScript project service](https://github.com/typescript-eslint/typescript-eslint/pull/6754) -- [docs: blog post on parserOptions.projectService](docs: blog post on parserOptions.projectService ) +- [docs: blog post on parserOptions.projectService](https://github.com/typescript-eslint/typescript-eslint/pull/8031) #### `ProjectServiceOptions` diff --git a/docs/troubleshooting/typed-linting/index.mdx b/docs/troubleshooting/typed-linting/index.mdx index f39e89876328..6a70c4a05ea0 100644 --- a/docs/troubleshooting/typed-linting/index.mdx +++ b/docs/troubleshooting/typed-linting/index.mdx @@ -25,32 +25,26 @@ See [ESLint does not re-compute cross-file information on file changes (microsof ## 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) `allowDefaultProject` with an excessively wide glob. -`allowDefaultProject` 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 `allowDefaultProject` to include fewer files. -For example: - -```diff title="eslint.config.js" -parserOptions: { - EXPERIMENTAL_useProjectService: { - allowDefaultProject: [ -- "**/*.js", -+ "./*.js" - ] - } -} -``` +These errors are caused by attempting to use the [`projectService`](../../packages/Parser.mdx#projectservice) to lint a file not explicitly included in a `tsconfig.json`. -You may also need to include more files in your `tsconfig.json`. -For example: +For each file being reported: -```diff title="tsconfig.json" -"include": [ - "src", -+ "*.js" -] -``` +- If you **do not** want to lint the file: + - Use [one of the options ESLint offers to ignore files](https://eslint.org/docs/latest/user-guide/configuring/ignoring-code), such an `ignores` config key. +- 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): [disable type-checked linting for that file](#how-do-i-disable-type-checked-linting-for-a-file). + - If you **do** want to lint the file with [type-aware linting](../../getting-started/Typed_Linting.mdx): + 1. If possible, add the file to the closest `tsconfig.json`'s `include`. For example, allowing `.js` files: + ```diff title="tsconfig.json" + "include": [ + "src", + + "*.js" + ] + ``` + 2. Otherwise, consider setting [`parserOptions.createProjectService.allowDefaultProject`](../../packages/parser#allowdefaultproject). + +typescript-eslint allows up to 8 "out of project" files by default. +Each file causes a new TypeScript "program" to be built for each file it includes, which incurs a performance overhead _for each file_. 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! @@ -61,46 +55,11 @@ These errors are caused by an ESLint config requesting type information be gener ### 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. + - Use [one of the options ESLint offers to ignore files](https://eslint.org/docs/latest/user-guide/configuring/ignoring-code), 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. + - Use [ESLint's configuration objects](https://eslint.org/docs/latest/use/configure/configuration-files#specifying-files-with-arbitrary-extensions) with our [`disable-type-checked`](../../users/Shared_Configurations.mdx#disable-type-checked) config to disable type checking for just that type of file. - 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. @@ -108,8 +67,6 @@ These errors are caused by an ESLint config requesting type information be gener - [`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: @@ -136,39 +93,46 @@ See our docs on [type aware linting](../../getting-started/Typed_Linting.mdx) fo 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 disable type-checked linting for a file? -## I get errors telling me "Having many files run with the default project is known to cause performance issues and slow down linting." +Use [ESLint's configuration objects](https://eslint.org/docs/latest/use/configure/configuration-files#specifying-files-with-arbitrary-extensions) with our [`disable-type-checked`](../../users/Shared_Configurations.mdx#disable-type-checked) config to disable type checking for a `files` match that includes that file. -These errors are caused by using the [`EXPERIMENTAL_useProjectService`](../../packages/Parser.mdx#experimental_useprojectservice) `allowDefaultProject` with an excessively wide glob. -`allowDefaultProject` causes a new TypeScript "program" to be built for each "out of project" file it includes, which incurs a performance overhead for each file. +For example, to disable type-checked linting on all `.js` files: -To resolve this error, narrow the glob(s) used for `allowDefaultProject` to include fewer files. -For example: + + -```diff title="eslint.config.js" -parserOptions: { - EXPERIMENTAL_useProjectService: { - allowDefaultProject: [ -- "**/*.js", -+ "./*.js" - ] - } -} -``` +```js title="eslint.config.js" +import tseslint from 'typescript-eslint'; -You may also need to include more files in your `tsconfig.json`. -For example: +export default tseslint.config( + // ... the rest of your config ... + { + files: ['**/*.js'], + extends: [tseslint.configs.disableTypeChecked], + }, +); +``` -```diff title="tsconfig.json" -"include": [ - "src", -+ "*.js" -] + + + +```js title=".eslintrc.cjs" +module.exports = { + // ... the rest of your config ... + overrides: [ + { + extends: ['plugin:@typescript-eslint/disable-type-checked'], + files: ['./**/*.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! + + + +Alternatively to disable type checking for files manually, you can set [`parserOptions: { project: false }`](../../packages/Parser.mdx#project) to an override for the files you wish to exclude. ## typescript-eslint thinks my variable is never nullish / is `any` / etc., but that is clearly not the case to me