docs: mention strict and stylistic configs in Getting Started (typesc…

…ript-eslint#8916) * docs: mention strict and stylistic configs in Getting Started * small touchups * Update docs/packages/Parser.mdx Co-authored-by: Kirk Waiblinger <53019676+kirkwaiblinger@users.noreply.github.com> --------- Co-authored-by: Kirk Waiblinger <53019676+kirkwaiblinger@users.noreply.github.com>
omril1 · Apr 26, 2024 · 323daae · 323daae
1 parent 51d2193
commit 323daae
Show file tree

Hide file tree

Showing 5 changed files with 177 additions and 66 deletions.
diff --git a/docs/getting-started/Legacy_ESLint_Setup.mdx b/docs/getting-started/Legacy_ESLint_Setup.mdx
@@ -84,10 +84,40 @@ ESLint will lint all TypeScript compatible files within the current folder, and
 
 ## Next Steps
 
-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).
-
 If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx).
 
+### Additional Configs
+
+We recommend you consider enabling the following two configs:
+
+- [`strict`](../users/Shared_Configurations.mdx#strict): a superset of `recommended` that includes more opinionated rules which may also catch bugs.
+- [`stylistic`](../users/Shared_Configurations.mdx#stylistic): additional rules that enforce consistent styling without significantly catching bugs or changing logic.
+
+```js title=".eslintrc.cjs"
+/* eslint-env node */
+module.exports = {
+  extends: [
+    'eslint:recommended',
+    // Remove this line
+    'plugin:@typescript-eslint/recommended',
+    // Added lines start
+    'plugin:@typescript-eslint/strict',
+    'plugin:@typescript-eslint/stylistic',
+    // Added lines end
+  ],
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  root: true,
+};
+```
+
+You can read more about these in our [shared configurations docs](../users/Shared_Configurations.mdx).
+
+### 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).
+
 ### Documentation Resources
 
 - You can read more about configuring ESLint [in their documentation on configuration](https://eslint.org/docs/user-guide/configuring).

diff --git a/docs/getting-started/Quickstart.mdx b/docs/getting-started/Quickstart.mdx
@@ -8,18 +8,17 @@ pagination_next: getting-started/typed-linting
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
+## Quickstart
+
+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.
+
 :::note
-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.
 
 - 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).
 - For quickstart information on linting with type information — see [Typed Linting](./Typed_Linting.mdx).
 
 :::
 
-## Quickstart
-
-These steps will get you running ESLint with our recommended rules on your TypeScript code as quickly as possible.
-
 ### Step 1: Installation
 
 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
 - `'@eslint/js'` / `eslint.configs.recommended` turns on [eslint's recommended config](https://www.npmjs.com/package/@eslint/js).
 - `...tseslint.configs.recommended` turns on [our recommended config](../users/Shared_Configurations.mdx#recommended).
 
-See [ESLint's Configuration Files docs](https://eslint.org/docs/user-guide/configuring/configuration-files-new) for more details on configuring ESLint.
-
 ## Next Steps
 
-We provide a plethora of powerful rules that utilize the power of TypeScript's type information.
+If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx).
 
-[Visit the next page for a setup guide](./Typed_Linting.mdx 'Visit the next page for a typed rules setup guide').
+### Additional Configs
 
-If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx).
+We recommend you consider enabling the following two configs:
+
+- [`strict`](../users/Shared_Configurations.mdx#strict): a superset of `recommended` that includes more opinionated rules which may also catch bugs.
+- [`stylistic`](../users/Shared_Configurations.mdx#stylistic): additional rules that enforce consistent styling without significantly catching bugs or changing logic.
+
+```js title="eslint.config.js"
+export default tseslint.config(
+  eslint.configs.recommended,
+  // Remove this line
+  ...tseslint.configs.recommended,
+  // Add this line
+  ...tseslint.configs.strict,
+  // Add this line
+  ...tseslint.configs.stylistic,
+);
+```
+
+You can read more about these in our [shared configurations docs](../users/Shared_Configurations.mdx).
+
+### 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).
 
-### Documentation Resources
+## Documentation Resources
 
 - You can read more about configuring ESLint [in their documentation on configuration](https://eslint.org/docs/user-guide/configuring).
 - You can read more about the rules provided by ESLint [in their documentation on their rules](https://eslint.org/docs/rules/).
-- You can read more about the rules provided by typescript-eslint in [our rules documentation](/rules).
+- You can read more about the rules provided by typescript-eslint in our [rules documentation](/rules).
diff --git a/docs/getting-started/Typed_Linting.mdx b/docs/getting-started/Typed_Linting.mdx
@@ -13,6 +13,9 @@ To tap into TypeScript's additional powers, there are two small changes you need
 <Tabs groupId="eslint-config">
 <TabItem value="Flat Config">
 
+1. Add `TypeChecked` to the name of any preset configs you're using, namely `recommended`, `strict`, and `stylistic`.
+2. Add `languageOptions.parserOptions` to tell our parser how to find the TSConfig for each source file.
+
 ```js title="eslint.config.js"
 export default tseslint.config(
   eslint.configs.recommended,
@@ -39,13 +42,16 @@ For CommonJS modules and/or older versions of Node.js, [use `__dirname` or an al
 
 In more detail:
 
-- `tseslint.configs.recommendedTypeChecked` is another [recommended configuration](../users/Shared_Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
-- `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)
-  - If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx).
+- `tseslint.configs.recommendedTypeChecked` is another [shared configuration](../users/Shared_Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
+- `parserOptions.project: true` indicates to find the closest `tsconfig.json` for each source file (see [Parser#project](../packages/Parser.mdx#project)).
+- `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory (see [Parser#tsconfigRootDir](../packages/Parser.mdx#tsconfigrootdir)).
 
 </TabItem>
 <TabItem value="Legacy Config">
 
+1. Add `-type-checked` to the name of any preset configs you're using, namely `recommended`, `strict`, and `stylistic`.
+2. Add `parserOptions` to tell our parser how to find the TSConfig for each source file.
+
 ```js title=".eslintrc.cjs"
 /* eslint-env node */
 module.exports = {
@@ -70,9 +76,8 @@ module.exports = {
 
 In more detail:
 
-- `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.
-- `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)
-  - If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx).
+- `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.
+- `parserOptions.project: true` indicates to find the closest `tsconfig.json` for each source file (see [Parser#project](../packages/Parser.mdx#project)).
 - `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory (see [Parser#tsconfigRootDir](../packages/Parser.mdx#tsconfigrootdir)).
 
 </TabItem>
@@ -86,7 +91,57 @@ See [our TSConfig inclusion FAQ](../troubleshooting/FAQ.mdx#i-get-errors-telling
 With that done, run the same lint command you ran before.
 You may see new rules reporting errors based on type information!
 
-## Specifying TSConfigs
+## Shared Configurations
+
+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.
+
+<Tabs groupId="eslint-config">
+<TabItem value="Flat Config">
+
+```js title="eslint.config.js"
+export default tseslint.config(
+  eslint.configs.recommended,
+  // Removed lines start
+  ...tseslint.configs.strict,
+  ...tseslint.configs.stylistic,
+  // Removed lines end
+  // Added lines start
+  ...tseslint.configs.strictTypeChecked,
+  ...tseslint.configs.stylisticTypeChecked,
+  // Added lines end
+  // ...
+);
+```
+
+</TabItem>
+<TabItem value="Legacy Config">
+
+```js title=".eslintrc.cjs"
+/* eslint-env node */
+module.exports = {
+  extends: [
+    'eslint:recommended',
+    // Removed lines start
+    'plugin:@typescript-eslint/strict',
+    'plugin:@typescript-eslint/stylistic',
+    // Removed lines end
+    // Added lines start
+    'plugin:@typescript-eslint/strict-type-checked',
+    'plugin:@typescript-eslint/stylistic-type-checked',
+    // Added lines end
+  ],
+  // ...
+};
+```
+
+</TabItem>
+</Tabs>
+
+You can read more about the rules provided by typescript-eslint in our [rules docs](/rules) and [shared configurations docs](../users/Shared_Configurations.mdx).
+
+## FAQs
+
+### Can I customize the TSConfig used for typed linting?
 
 The `project` option can be turned on with either:
 
@@ -134,8 +189,6 @@ See [the `@typescript-eslint/parser` docs for more details](../packages/Parser.m
 If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx).
 :::
 
-## FAQs
-
 ### How can I disable type-aware linting for a subset of files?
 
 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
 export default tseslint.config(
   eslint.configs.recommended,
   ...tseslint.configs.recommendedTypeChecked,
+  ...tseslint.configs.stylisticTypeChecked,
   {
     languageOptions: {
       parserOptions: {
@@ -156,7 +210,7 @@ export default tseslint.config(
   },
   // Added lines start
   {
-    files: ['*.js'],
+    files: ['**/*.js'],
     ...tseslint.configs.disableTypeChecked,
   },
   // Added lines end
@@ -171,6 +225,7 @@ module.exports = {
   extends: [
     'eslint:recommended',
     'plugin:@typescript-eslint/recommended-type-checked',
+    'plugin:@typescript-eslint/stylistic-type-checked',
   ],
   plugins: ['@typescript-eslint'],
   parser: '@typescript-eslint/parser',
@@ -209,11 +264,6 @@ This means that generally they usually only run a complete lint before a push, o
 
 **We strongly recommend you do use type-aware linting**, but the above information is included so that you can make your own, informed decision.
 
-### 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 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).
-
 ## Troubleshooting
 
 If you're having problems getting this working, please have a look at our [Troubleshooting and FAQs page](../troubleshooting/FAQ.mdx).
diff --git a/docs/packages/Parser.mdx b/docs/packages/Parser.mdx
@@ -169,7 +169,7 @@ The identifier that's used for JSX fragment elements (after transpilation).
 If `null`, assumes transpilation will always use a member of the configured `jsxPragma`.
 This should not be a member expression - just the root identifier (i.e. use `"h"` instead of `"h.Fragment"`).
 
-If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler.
+If you provide `parserOptions.project`, you do not need to set this, as it will be automatically detected from the compiler.
 
 ### `jsxPragma`
 
@@ -180,7 +180,7 @@ If you're using a library other than React (like `preact`), then you should chan
 
 This should not be a member expression - just the root identifier (i.e. use `"React"` instead of `"React.createElement"`).
 
-If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler.
+If you provide `parserOptions.project`, you do not need to set this, as it will be automatically detected from the compiler.
 
 ### `lib`
 
@@ -190,7 +190,7 @@ For valid options, see the [TypeScript compiler options](https://www.typescriptl
 
 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.
 
-If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler.
+If you provide `parserOptions.project`, you do not need to set this, as it will be automatically detected from the compiler.
 
 ### `programs`
 
@@ -206,27 +206,27 @@ All linted files must be part of the provided program(s).
 
 > Default `undefined`.
 
-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`.
+A path to your project's TSConfig. **This setting is required to use [rules which require type information](../getting-started/Typed_Linting.mdx)**.
 
-- Accepted values:
+Accepted value types:
 
-  ```js
-  // find the tsconfig.json nearest each source file
-  project: true,
+```js
+// find the tsconfig.json nearest to each source file
+project: true,
 
-  // path
-  project: './tsconfig.json';
+// path
+project: './tsconfig.json';
 
-  // glob pattern
-  project: './packages/**/tsconfig.json';
+// glob pattern
+project: './packages/**/tsconfig.json';
 
-  // array of paths and/or glob patterns
-  project: ['./packages/**/tsconfig.json', './separate-package/tsconfig.json'];
+// array of paths and/or glob patterns
+project: ['./packages/**/tsconfig.json', './separate-package/tsconfig.json'];
 
-  // ways to disable type-aware linting (useful for overrides configs)
-  project: false;
-  project: null;
-  ```
+// ways to disable type-aware linting (useful for overrides configs)
+project: false;
+project: null;
+```
 
 - If `true`, each source file's parse will find the nearest `tsconfig.json` file to that source file.
 
@@ -236,25 +236,31 @@ This option allows you to provide a path to your project's `tsconfig.json`. **Th
 
 - 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).
 
-- 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.
-
-- 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:
-
-  ```jsonc
-  {
-    // extend your base config so you don't have to redefine your compilerOptions
-    "extends": "./tsconfig.json",
-    "include": [
-      "src/**/*.ts",
-      "test/**/*.ts",
-      "typings/**/*.ts",
-      // etc
-
-      // if you have a mixed JS/TS codebase, don't forget to include your JS files
-      "src/**/*.js",
-    ],
-  }
-  ```
+- 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).
+
+:::note
+Relative paths are interpreted relative to the current working directory if [`tsconfigRootDir`](#tsconfigrootdir) is not set.
+:::
+
+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:
+
+```jsonc
+{
+  // extend your base config so you don't have to redefine your compilerOptions
+  "extends": "./tsconfig.json",
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts",
+    "typings/**/*.ts",
+    // etc
+
+    // if you have a mixed JS/TS codebase, don't forget to include your JS files
+    "src/**/*.js",
+  ],
+}
+```
+
+For an option that allows linting files outside of your TSConfig file(s), see [`EXPERIMENTAL_useProjectService`](#experimental_useprojectservice).
 
 ### `projectFolderIgnoreList`
 

diff --git a/docs/users/Shared_Configurations.mdx b/docs/users/Shared_Configurations.mdx
@@ -240,6 +240,9 @@ module.exports = {
 </TabItem>
 </Tabs>
 
+Note that `stylistic` does not replace `recommended` or `strict`.
+`stylistic` adds additional rules.
+
 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.
 
 ### `stylistic-type-checked`
@@ -266,6 +269,9 @@ module.exports = {
 </TabItem>
 </Tabs>
 
+Note that `stylistic-type-checked` does not replace `recommended-type-checked` or `strict-type-checked`.
+`stylistic-type-checked` adds additional rules.
+
 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.
 
 ## Other Configurations