Skip to content

docs: clarify projectService out-of-project remediation steps #9585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 21, 2024
Merged

docs: clarify projectService out-of-project remediation steps #9585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/packages/Parser.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down
140 changes: 52 additions & 88 deletions docs/troubleshooting/typed-linting/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand All @@ -61,55 +55,18 @@ These errors are caused by an ESLint config requesting type information be gener

### Fixing the Error

<!-- prettier-ignore-start -->

- 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.
<Tabs groupId="eslint-config">
<TabItem value="Flat Config">

```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],
},
);
```

</TabItem>
<TabItem value="Legacy Config">

```js title=".eslintrc.cjs"
module.exports = {
// ... the rest of your config ...
overrides: [
{
extends: ['plugin:@typescript-eslint/disable-type-checked'],
files: ['./**/*.js'],
},
],
};
```

</TabItem>
</Tabs>
- 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.
- 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)

<!-- prettier-ignore-end -->

### More Details

This error may appear from the combination of two things:
Expand All @@ -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 ...').

<HiddenHeading id="allowdefaultproject-glob-too-wide" />
## 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:
<Tabs groupId="eslint-config">
<TabItem value="Flat Config">

```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"
]
</TabItem>
<TabItem value="Legacy Config">

```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!
</TabItem>
</Tabs>

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

Expand Down
Loading