Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork2.8k
docs: add more project service docs and FAQs#9871
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.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Changes fromall commits
File filter
Filter by extension
Conversations
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -283,7 +283,8 @@ For an option that allows linting files outside of your TSConfig file(s), see [` | ||
> Default `false`. | ||
Specifies using TypeScript APIs to generate type information for rules. | ||
It will automatically use the nearest `tsconfig.json` for each file (like `project: true`). | ||
It can also be configured to also allow type information to be computed for JavaScript files without the `allowJs` compiler option (unlike `project: true`). | ||
<Tabs groupId="eslint-config"> | ||
<TabItem value="Flat Config"> | ||
@@ -320,24 +321,21 @@ module.exports = { | ||
This option brings two main benefits over the older `project`: | ||
- Simpler configurations: most projects shouldn't need to explicitly configure `project` paths or create `tsconfig.eslint.json`s | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. We're still working on performance & filling in the gaps on edge cases. IMO we should stop bragging about it until we can be very, very certain it's better the vast majority of the time. | ||
- Predictability: it uses the same type information services as editors, giving better consistency with the types seen in editors | ||
See [FAQs > Typed Linting > Project Service Issues](../troubleshooting/typed-linting/index.mdx#project-service-issues) for help on working with the project service. | ||
#### `ProjectServiceOptions` | ||
The behavior of `parserOptions.projectService` can be customized by setting it to an object. | ||
```js | ||
{ | ||
parser: '@typescript-eslint/parser', | ||
parserOptions: { | ||
projectService: { | ||
allowDefaultProject: ['*.js'], | ||
defaultProject: 'tsconfig.json', | ||
}, | ||
}, | ||
}; | ||
@@ -346,10 +344,24 @@ module.exports = { | ||
##### `allowDefaultProject` | ||
Globs of files to allow running with the default project compiler options despite not being matched by the project service. | ||
It takes in an array of string paths that will be resolved relative to the [`tsconfigRootDir`](#tsconfigrootdir). | ||
When set, [`projectService.defaultProject`](#defaultproject) must be set as well. | ||
This is intended to produce type information for config files such as `eslint.config.js` that aren't included in their sibling `tsconfig.json`. | ||
Every file with type information retrieved from the default project incurs a non-trivial performance overhead to linting. | ||
Use this option sparingly. | ||
There are several restrictions on this option to prevent it from being overused: | ||
- `**` is not allowed in globs passed to it | ||
- Files that match `allowDefaultProject` may not also be included in their nearest `tsconfig.json` | ||
##### `defaultProject` | ||
Path to a TSConfig to use instead of TypeScript's default project configuration. | ||
It takes in a string path that will be resolved relative to the [`tsconfigRootDir`](#tsconfigrootdir). | ||
This is required to specify which TSConfig file on disk will be used for [`projectService.allowDefaultProject`](#allowdefaultproject). | ||
##### `maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING` | ||
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -84,18 +84,21 @@ If the IDE provides different type information from typescript-eslint's report, | ||
## Are TypeScript project references supported? | ||
Yes, but only with [`parserOptions.projectService`](../../packages/Parser.mdx#projectservice). | ||
See [issue #2094 discussing project references](https://github.com/typescript-eslint/typescript-eslint/issues/2094) for more details. | ||
## Project Service Issues | ||
MemberAuthor
| ||
[`parserOptions.projectService`](../../packages/Parser.mdx#projectservice) is the recommended parser option to enable typed linting as of typescript-eslint v8. | ||
It enforces projects generate type information for typed linting from the same `tsconfig.json` files used by editors such as VS Code. | ||
### I get errors telling me "... was not found by the project service. Consider either including it in the tsconfig.json or including it in allowDefaultProject" | ||
These errors are caused by attempting to use the project service to lint a file not explicitly included in its nearest `tsconfig.json`. | ||
The project service will attempt to build type information for each file being linted using the nearest `tsconfig.json` on disk to that file. | ||
If that `tsconfig.json` does not include the file, and the file isn't allowlisted in [`allowDefaultProject`](../../packages/parser#allowdefaultproject), then the project service will throw this error. | ||
For each file being reported: | ||
@@ -111,13 +114,61 @@ For each file being reported: | ||
+ "*.js" | ||
] | ||
``` | ||
2. Otherwise, if you have a small number of "out of project" files, try setting [`projectService.allowDefaultProject`](../../packages/parser#allowdefaultproject). | ||
3. If not, you can switch to [`parserOptions.project`](../../packages/Parser.mdx#project) for more fine-grained control of projects. | ||
Note also: | ||
- TSConfigs don't include `.js` files by default. | ||
Enabling [`allowJs`](https://www.typescriptlang.org/tsconfig/#allowJs) or [`checkJs`](https://www.typescriptlang.org/tsconfig/#checkJs) is required to do so. | ||
- The project service _only_ looks at `tsconfig.json` files. | ||
It does not look at `tsconfig.eslint.json` or other coincidentally-similarly-named files. | ||
If these steps don't work for you, 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! | ||
<HiddenHeading id="allowdefaultproject-glob-too-wide" /> | ||
### 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 attempting to use the project service to lint too many files not explicitly included in a `tsconfig.json` with its [`allowDefaultProject`](../../packages/parser#allowdefaultproject) option. | ||
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_. | ||
For each file being reported: | ||
- 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` instead of adding it to `allowDefaultProject`. For example, allowing `.js` files: | ||
```diff title="tsconfig.json" | ||
"include": [ | ||
"src", | ||
+ "*.js" | ||
] | ||
``` | ||
2. If not, you can switch to [`parserOptions.project`](../../packages/Parser.mdx#project) for more fine-grained control of projects. | ||
### I'd like to use TSConfigs other than `tsconfig.json`s for project service type information | ||
Only the TSConfig path used for "out of project" files in [`allowDefaultProject`](../../packages/Parser.mdx#allowdefaultproject) can be customized. | ||
Otherwise, only `tsconfig.json` files on disk will be read. | ||
For example, instead of: | ||
- `tsconfig.json`s for building (and, coincidentally, type information in editors) | ||
- Separate TSConfig(s) like `tsconfig.eslint.json` for linting | ||
Consider using: | ||
- `tsconfig.json`s for linting (and, intentionally, the same type information in editors) | ||
- Separate TSConfig(s) like `tsconfig.build.json` for building | ||
The project service uses the same underlying TypeScript logic as editors such as VS Code. | ||
Using only `tsconfig.json` for typed linting enforces that the types seen in your editor match what's used for linting. | ||
## Traditional Project Issues | ||
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -211,3 +211,7 @@ h6 { | ||
td > p:last-child { | ||
margin-bottom: 0; | ||
} | ||
h5 { | ||
font-weight: bold; | ||
} | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. It was bugging me that the h5s under |
Uh oh!
There was an error while loading.Please reload this page.