Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 323daae

Browse files
JoshuaKGoldbergkirkwaiblinger
JoshuaKGoldberg
and
kirkwaiblinger
authored
docs: mention strict and stylistic configs in Getting Started (typescript-eslint#8916)
* docs: mention strict and stylistic configs in Getting Started * small touchups * Update docs/packages/Parser.mdx Co-authored-by: Kirk Waiblinger <[email protected]> --------- Co-authored-by: Kirk Waiblinger <[email protected]>
1 parent 51d2193 commit 323daae

File tree

5 files changed

+177
-66
lines changed

5 files changed

+177
-66
lines changed

‎docs/getting-started/Legacy_ESLint_Setup.mdx

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,10 +84,40 @@ ESLint will lint all TypeScript compatible files within the current folder, and
8484

8585
## Next Steps
8686

87-
We provide a plethora of powerful rules that utilize the power of TypeScript's type information. [Visit _Typed Rules_ for a setup guide](./Typed_Linting.mdx).
88-
8987
If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx).
9088

89+
### Additional Configs
90+
91+
We recommend you consider enabling the following two configs:
92+
93+
- [`strict`](../users/Shared_Configurations.mdx#strict): a superset of `recommended` that includes more opinionated rules which may also catch bugs.
94+
- [`stylistic`](../users/Shared_Configurations.mdx#stylistic): additional rules that enforce consistent styling without significantly catching bugs or changing logic.
95+
96+
```js title=".eslintrc.cjs"
97+
/* eslint-env node */
98+
module.exports = {
99+
extends: [
100+
'eslint:recommended',
101+
// Remove this line
102+
'plugin:@typescript-eslint/recommended',
103+
// Added lines start
104+
'plugin:@typescript-eslint/strict',
105+
'plugin:@typescript-eslint/stylistic',
106+
// Added lines end
107+
],
108+
parser: '@typescript-eslint/parser',
109+
plugins: ['@typescript-eslint'],
110+
root: true,
111+
};
112+
```
113+
114+
You can read more about these in our [shared configurations docs](../users/Shared_Configurations.mdx).
115+
116+
### Typed Linting
117+
118+
We also provide a plethora of powerful rules that utilize the power of TypeScript's type information.
119+
[Visit the next page for a typed rules setup guide](./Typed_Linting.mdx).
120+
91121
### Documentation Resources
92122

93123
- You can read more about configuring ESLint [in their documentation on configuration](https://eslint.org/docs/user-guide/configuring).

‎docs/getting-started/Quickstart.mdx

Lines changed: 31 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,17 @@ pagination_next: getting-started/typed-linting
88
import Tabs from '@theme/Tabs';
99
import TabItem from '@theme/TabItem';
1010

11+
## Quickstart
12+
13+
This page is a quick-start for [ESLint's new "flat" config format](https://eslint.org/docs/latest/use/configure/configuration-files-new) to go from zero to linting with our recommended rules on your TypeScript code as quickly as possible.
14+
1115
:::note
12-
This page is a quick-start guide for [ESLint's new "flat" config format](https://eslint.org/docs/latest/use/configure/configuration-files-new) to help you go from zero to linting as quick as possible.
1316

1417
- For the same guide but for [ESLint's legacy format](https://eslint.org/docs/latest/use/configure/configuration-files) — see [Legacy ESLint Setup](./Legacy_ESLint_Setup.mdx).
1518
- For quickstart information on linting with type information — see [Typed Linting](./Typed_Linting.mdx).
1619

1720
:::
1821

19-
## Quickstart
20-
21-
These steps will get you running ESLint with our recommended rules on your TypeScript code as quickly as possible.
22-
2322
### Step 1: Installation
2423

2524
First, install the required packages for [ESLint](https://eslint.org), [TypeScript](https://typescriptlang.org), and [our tooling](../packages/TypeScript_ESLint.mdx):
@@ -82,18 +81,38 @@ ESLint will lint all TypeScript compatible files within the current folder, and
8281
- `'@eslint/js'` / `eslint.configs.recommended` turns on [eslint's recommended config](https://www.npmjs.com/package/@eslint/js).
8382
- `...tseslint.configs.recommended` turns on [our recommended config](../users/Shared_Configurations.mdx#recommended).
8483

85-
See [ESLint's Configuration Files docs](https://eslint.org/docs/user-guide/configuring/configuration-files-new) for more details on configuring ESLint.
86-
8784
## Next Steps
8885

89-
We provide a plethora of powerful rules that utilize the power of TypeScript's type information.
86+
If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx).
9087

91-
[Visit the next page for a setup guide](./Typed_Linting.mdx 'Visit the next page for a typed rules setup guide').
88+
### Additional Configs
9289

93-
If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx).
90+
We recommend you consider enabling the following two configs:
91+
92+
- [`strict`](../users/Shared_Configurations.mdx#strict): a superset of `recommended` that includes more opinionated rules which may also catch bugs.
93+
- [`stylistic`](../users/Shared_Configurations.mdx#stylistic): additional rules that enforce consistent styling without significantly catching bugs or changing logic.
94+
95+
```js title="eslint.config.js"
96+
export default tseslint.config(
97+
eslint.configs.recommended,
98+
// Remove this line
99+
...tseslint.configs.recommended,
100+
// Add this line
101+
...tseslint.configs.strict,
102+
// Add this line
103+
...tseslint.configs.stylistic,
104+
);
105+
```
106+
107+
You can read more about these in our [shared configurations docs](../users/Shared_Configurations.mdx).
108+
109+
### Typed Linting
110+
111+
We also provide a plethora of powerful rules that utilize the power of TypeScript's type information.
112+
[Visit the next page for a typed rules setup guide](./Typed_Linting.mdx).
94113

95-
### Documentation Resources
114+
## Documentation Resources
96115

97116
- You can read more about configuring ESLint [in their documentation on configuration](https://eslint.org/docs/user-guide/configuring).
98117
- You can read more about the rules provided by ESLint [in their documentation on their rules](https://eslint.org/docs/rules/).
99-
- You can read more about the rules provided by typescript-eslint in [our rules documentation](/rules).
118+
- You can read more about the rules provided by typescript-eslint in our [rules documentation](/rules).

‎docs/getting-started/Typed_Linting.mdx

Lines changed: 65 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ To tap into TypeScript's additional powers, there are two small changes you need
1313
<Tabs groupId="eslint-config">
1414
<TabItem value="Flat Config">
1515

16+
1. Add `TypeChecked` to the name of any preset configs you're using, namely `recommended`, `strict`, and `stylistic`.
17+
2. Add `languageOptions.parserOptions` to tell our parser how to find the TSConfig for each source file.
18+
1619
```js title="eslint.config.js"
1720
export default tseslint.config(
1821
eslint.configs.recommended,
@@ -39,13 +42,16 @@ For CommonJS modules and/or older versions of Node.js, [use `__dirname` or an al
3942

4043
In more detail:
4144

42-
- `tseslint.configs.recommendedTypeChecked` is another [recommended configuration](../users/Shared_Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
43-
- `parserOption.project` tells our parser how to find the TSConfig for each source file (`true` indicates to find the closest `tsconfig.json` for each source file)
44-
- If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx).
45+
- `tseslint.configs.recommendedTypeChecked` is another [shared configuration](../users/Shared_Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
46+
- `parserOptions.project: true` indicates to find the closest `tsconfig.json` for each source file (see [Parser#project](../packages/Parser.mdx#project)).
47+
- `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory (see [Parser#tsconfigRootDir](../packages/Parser.mdx#tsconfigrootdir)).
4548

4649
</TabItem>
4750
<TabItem value="Legacy Config">
4851

52+
1. Add `-type-checked` to the name of any preset configs you're using, namely `recommended`, `strict`, and `stylistic`.
53+
2. Add `parserOptions` to tell our parser how to find the TSConfig for each source file.
54+
4955
```js title=".eslintrc.cjs"
5056
/* eslint-env node */
5157
module.exports = {
@@ -70,9 +76,8 @@ module.exports = {
7076

7177
In more detail:
7278

73-
- `plugin:@typescript-eslint/recommended-type-checked` is another [recommended configuration](../users/Shared_Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
74-
- `parserOptions.project` tells our parser how to find the TSConfig for each source file (`true` indicates to find the closest `tsconfig.json` for each source file)
75-
- If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx).
79+
- `plugin:@typescript-eslint/recommended-type-checked` is another [shared configuration](../users/Shared_Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
80+
- `parserOptions.project: true` indicates to find the closest `tsconfig.json` for each source file (see [Parser#project](../packages/Parser.mdx#project)).
7681
- `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory (see [Parser#tsconfigRootDir](../packages/Parser.mdx#tsconfigrootdir)).
7782

7883
</TabItem>
@@ -86,7 +91,57 @@ See [our TSConfig inclusion FAQ](../troubleshooting/FAQ.mdx#i-get-errors-telling
8691
With that done, run the same lint command you ran before.
8792
You may see new rules reporting errors based on type information!
8893

89-
## Specifying TSConfigs
94+
## Shared Configurations
95+
96+
If you enabled the [`strict` shared config](../users/Shared_Configurations.mdx#strict) and/or [`stylistic` shared config](../users/Shared_Configurations.mdx#stylistic) in a previous step, be sure to replace them with [`strictTypeChecked`](../users/Shared_Configurations.mdx#strict-type-checked) and [`stylisticTypeChecked`](../users/Shared_Configurations.mdx#stylistic-type-checked) respectively to add their type-checked rules.
97+
98+
<Tabs groupId="eslint-config">
99+
<TabItem value="Flat Config">
100+
101+
```js title="eslint.config.js"
102+
export default tseslint.config(
103+
eslint.configs.recommended,
104+
// Removed lines start
105+
...tseslint.configs.strict,
106+
...tseslint.configs.stylistic,
107+
// Removed lines end
108+
// Added lines start
109+
...tseslint.configs.strictTypeChecked,
110+
...tseslint.configs.stylisticTypeChecked,
111+
// Added lines end
112+
// ...
113+
);
114+
```
115+
116+
</TabItem>
117+
<TabItem value="Legacy Config">
118+
119+
```js title=".eslintrc.cjs"
120+
/* eslint-env node */
121+
module.exports = {
122+
extends: [
123+
'eslint:recommended',
124+
// Removed lines start
125+
'plugin:@typescript-eslint/strict',
126+
'plugin:@typescript-eslint/stylistic',
127+
// Removed lines end
128+
// Added lines start
129+
'plugin:@typescript-eslint/strict-type-checked',
130+
'plugin:@typescript-eslint/stylistic-type-checked',
131+
// Added lines end
132+
],
133+
// ...
134+
};
135+
```
136+
137+
</TabItem>
138+
</Tabs>
139+
140+
You can read more about the rules provided by typescript-eslint in our [rules docs](/rules) and [shared configurations docs](../users/Shared_Configurations.mdx).
141+
142+
## FAQs
143+
144+
### Can I customize the TSConfig used for typed linting?
90145

91146
The `project` option can be turned on with either:
92147

@@ -134,8 +189,6 @@ See [the `@typescript-eslint/parser` docs for more details](../packages/Parser.m
134189
If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx).
135190
:::
136191

137-
## FAQs
138-
139192
### How can I disable type-aware linting for a subset of files?
140193

141194
You can combine ESLint's [overrides](https://eslint.org/docs/latest/use/configure/configuration-files#configuration-based-on-glob-patterns) config in conjunction with our [`disable-type-checked`](../users/Shared_Configurations.mdx#disable-type-checked) config to turn off type-aware linting on specific subsets of files.
@@ -147,6 +200,7 @@ You can combine ESLint's [overrides](https://eslint.org/docs/latest/use/configur
147200
export default tseslint.config(
148201
eslint.configs.recommended,
149202
...tseslint.configs.recommendedTypeChecked,
203+
...tseslint.configs.stylisticTypeChecked,
150204
{
151205
languageOptions: {
152206
parserOptions: {
@@ -156,7 +210,7 @@ export default tseslint.config(
156210
},
157211
// Added lines start
158212
{
159-
files: ['*.js'],
213+
files: ['**/*.js'],
160214
...tseslint.configs.disableTypeChecked,
161215
},
162216
// Added lines end
@@ -171,6 +225,7 @@ module.exports = {
171225
extends: [
172226
'eslint:recommended',
173227
'plugin:@typescript-eslint/recommended-type-checked',
228+
'plugin:@typescript-eslint/stylistic-type-checked',
174229
],
175230
plugins: ['@typescript-eslint'],
176231
parser: '@typescript-eslint/parser',
@@ -209,11 +264,6 @@ This means that generally they usually only run a complete lint before a push, o
209264

210265
**We strongly recommend you do use type-aware linting**, but the above information is included so that you can make your own, informed decision.
211266

212-
### I get errors telling me "The file must be included in at least one of the projects provided"
213-
214-
You're using an outdated version of `@typescript-eslint/parser`.
215-
Update to the latest version to see a more informative version of this error message, explained in our [Troubleshooting and FAQs page](../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).
216-
217267
## Troubleshooting
218268

219269
If you're having problems getting this working, please have a look at our [Troubleshooting and FAQs page](../troubleshooting/FAQ.mdx).

‎docs/packages/Parser.mdx

Lines changed: 43 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,7 @@ The identifier that's used for JSX fragment elements (after transpilation).
169169
If `null`, assumes transpilation will always use a member of the configured `jsxPragma`.
170170
This should not be a member expression - just the root identifier (i.e. use `"h"` instead of `"h.Fragment"`).
171171

172-
If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler.
172+
If you provide `parserOptions.project`, you do not need to set this, as it will be automatically detected from the compiler.
173173

174174
### `jsxPragma`
175175

@@ -180,7 +180,7 @@ If you're using a library other than React (like `preact`), then you should chan
180180

181181
This should not be a member expression - just the root identifier (i.e. use `"React"` instead of `"React.createElement"`).
182182

183-
If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler.
183+
If you provide `parserOptions.project`, you do not need to set this, as it will be automatically detected from the compiler.
184184

185185
### `lib`
186186

@@ -190,7 +190,7 @@ For valid options, see the [TypeScript compiler options](https://www.typescriptl
190190

191191
Specifies the TypeScript `lib`s that are available. This is used by the scope analyser to ensure there are global variables declared for the types exposed by TypeScript.
192192

193-
If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler.
193+
If you provide `parserOptions.project`, you do not need to set this, as it will be automatically detected from the compiler.
194194

195195
### `programs`
196196

@@ -206,27 +206,27 @@ All linted files must be part of the provided program(s).
206206

207207
> Default `undefined`.
208208
209-
This option allows you to provide a path to your project's `tsconfig.json`. **This setting is required if you want to use rules which require type information**. Relative paths are interpreted relative to the current working directory if `tsconfigRootDir` is not set. If you intend on running ESLint from directories other than the project root, you should consider using `tsconfigRootDir`.
209+
A path to your project's TSConfig. **This setting is required to use [rules which require type information](../getting-started/Typed_Linting.mdx)**.
210210

211-
- Accepted values:
211+
Accepted value types:
212212

213-
```js
214-
// find the tsconfig.json nearest each source file
215-
project: true,
213+
```js
214+
// find the tsconfig.json nearest to each source file
215+
project: true,
216216

217-
// path
218-
project: './tsconfig.json';
217+
// path
218+
project: './tsconfig.json';
219219

220-
// glob pattern
221-
project: './packages/**/tsconfig.json';
220+
// glob pattern
221+
project: './packages/**/tsconfig.json';
222222

223-
// array of paths and/or glob patterns
224-
project: ['./packages/**/tsconfig.json', './separate-package/tsconfig.json'];
223+
// array of paths and/or glob patterns
224+
project: ['./packages/**/tsconfig.json', './separate-package/tsconfig.json'];
225225

226-
// ways to disable type-aware linting (useful for overrides configs)
227-
project: false;
228-
project: null;
229-
```
226+
// ways to disable type-aware linting (useful for overrides configs)
227+
project: false;
228+
project: null;
229+
```
230230

231231
- If `true`, each source file's parse will find the nearest `tsconfig.json` file to that source file.
232232

@@ -236,25 +236,31 @@ This option allows you to provide a path to your project's `tsconfig.json`. **Th
236236

237237
- Note that using wide globs `**` in your `parserOptions.project` may cause performance implications. Instead of globs that use `**` to recursively check all folders, prefer paths that use a single `*` at a time. For more info see [#2611](https://github.com/typescript-eslint/typescript-eslint/issues/2611).
238238

239-
- TypeScript will ignore files with duplicate filenames in the same folder (for example, `src/file.ts` and `src/file.js`). TypeScript purposely ignore all but one of the files, only keeping the one file with the highest priority extension (the extension priority order (from highest to lowest) is `.ts`, `.tsx`, `.d.ts`, `.js`, `.jsx`). For more info see #955.
240-
241-
- Note that if this setting is specified, you must only lint files that are included in the projects as defined by the provided `tsconfig.json` files. If your existing configuration does not include all of the files you would like to lint, you can create a separate `tsconfig.eslint.json` as follows:
242-
243-
```jsonc
244-
{
245-
// extend your base config so you don't have to redefine your compilerOptions
246-
"extends": "./tsconfig.json",
247-
"include": [
248-
"src/**/*.ts",
249-
"test/**/*.ts",
250-
"typings/**/*.ts",
251-
// etc
252-
253-
// if you have a mixed JS/TS codebase, don't forget to include your JS files
254-
"src/**/*.js",
255-
],
256-
}
257-
```
239+
- TypeScript will ignore files with duplicate filenames in the same folder (for example, `src/file.ts` and `src/file.js`). TypeScript purposely ignores all but one of the files, only keeping the one file with the highest priority extension (the extension priority order (from highest to lowest) is `.ts`, `.tsx`, `.d.ts`, `.js`, `.jsx`). For more info see [#955](https://github.com/typescript-eslint/typescript-eslint/issues/955).
240+
241+
:::note
242+
Relative paths are interpreted relative to the current working directory if [`tsconfigRootDir`](#tsconfigrootdir) is not set.
243+
:::
244+
245+
If this setting is specified, you must only lint files that are included in the projects as defined by the provided TSConfig file(s). If your existing configuration does not include all of the files you would like to lint, you can create a separate `tsconfig.eslint.json` as follows:
246+
247+
```jsonc
248+
{
249+
// extend your base config so you don't have to redefine your compilerOptions
250+
"extends": "./tsconfig.json",
251+
"include": [
252+
"src/**/*.ts",
253+
"test/**/*.ts",
254+
"typings/**/*.ts",
255+
// etc
256+
257+
// if you have a mixed JS/TS codebase, don't forget to include your JS files
258+
"src/**/*.js",
259+
],
260+
}
261+
```
262+
263+
For an option that allows linting files outside of your TSConfig file(s), see [`EXPERIMENTAL_useProjectService`](#experimental_useprojectservice).
258264

259265
### `projectFolderIgnoreList`
260266

‎docs/users/Shared_Configurations.mdx

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -240,6 +240,9 @@ module.exports = {
240240
</TabItem>
241241
</Tabs>
242242

243+
Note that `stylistic` does not replace `recommended` or `strict`.
244+
`stylistic` adds additional rules.
245+
243246
See [`configs/stylistic.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/stylistic.ts) for the exact contents of this config.
244247

245248
### `stylistic-type-checked`
@@ -266,6 +269,9 @@ module.exports = {
266269
</TabItem>
267270
</Tabs>
268271

272+
Note that `stylistic-type-checked` does not replace `recommended-type-checked` or `strict-type-checked`.
273+
`stylistic-type-checked` adds additional rules.
274+
269275
See [`configs/stylistic-type-checked.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/stylistic-type-checked.ts) for the exact contents of this config.
270276

271277
## Other Configurations

0 commit comments

Comments
 (0)