From 35d324a785194e446d042d9c2919582efb175421 Mon Sep 17 00:00:00 2001 From: Brad Zacher Date: Mon, 19 Feb 2024 17:12:41 +1030 Subject: [PATCH 1/3] docs: rework --- docs/Developers.mdx | 6 +- docs/Packages.mdx | 2 +- .../Legacy_ESLint_Setup.mdx | 4 +- .../Quickstart.mdx} | 40 +-- .../Typed_Linting.mdx | 13 +- .../typed-linting/Monorepos.mdx | 3 +- docs/maintenance/Issues.mdx | 2 +- docs/maintenance/Team.mdx | 2 +- docs/packages/ESLint_Plugin.mdx | 2 +- docs/packages/ESLint_Plugin_TSLint.mdx | 4 +- docs/packages/Parser.mdx | 4 +- docs/packages/TypeScript_ESLint.mdx | 123 ++++++++-- .../FAQ.mdx} | 232 +++++++++++++----- .../troubleshooting/Formatting.mdx | 30 ++- .../troubleshooting/Performance.mdx | 37 ++- docs/{linting => }/troubleshooting/TSLint.mdx | 2 +- docs/users/Releases.mdx | 14 +- .../Shared_Configurations.mdx} | 8 +- packages/typescript-eslint/src/index.ts | 72 +++++- packages/website/sidebars/sidebar.base.js | 48 ++-- 20 files changed, 469 insertions(+), 179 deletions(-) rename docs/{linting => getting-started}/Legacy_ESLint_Setup.mdx (93%) rename docs/{Getting_Started.mdx => getting-started/Quickstart.mdx} (51%) rename docs/{linting => getting-started}/Typed_Linting.mdx (87%) rename docs/{linting => getting-started}/typed-linting/Monorepos.mdx (98%) rename docs/{linting/Troubleshooting.mdx => troubleshooting/FAQ.mdx} (80%) rename docs/{linting => }/troubleshooting/Formatting.mdx (89%) rename docs/{linting => }/troubleshooting/Performance.mdx (88%) rename docs/{linting => }/troubleshooting/TSLint.mdx (97%) rename docs/{linting/Configurations.mdx => users/Shared_Configurations.mdx} (95%) diff --git a/docs/Developers.mdx b/docs/Developers.mdx index e1658aa105b7..7db3a7029c67 100644 --- a/docs/Developers.mdx +++ b/docs/Developers.mdx @@ -6,5 +6,7 @@ title: Developers These are the developer guides to working with the typescript-eslint tooling. It's intended for use by third-parties who want to use our tools to build great things. -> If you're reading this as a new developer: welcome to the community! -> We're happy to have you! ❤️‍🔥 +:::info Welcome! +If you're reading this as a new developer: welcome to the community! +We're happy to have you! ❤️‍🔥 +::: diff --git a/docs/Packages.mdx b/docs/Packages.mdx index 8f4c27472f2b..2235d57b21ae 100644 --- a/docs/Packages.mdx +++ b/docs/Packages.mdx @@ -12,7 +12,7 @@ As of v7 and ESLint 9, most users should be using the **[`typescript-eslint`](./ It exports configurations for ESLint and brings along the corresponding versions of other packages as dependencies. :::tip -See [Getting Started](./Getting_Started.mdx) for guidance on setting up typescript-eslint on a project. +See [Getting Started](./getting-started/Quickstart.mdx) for guidance on setting up typescript-eslint on a project. ::: ## Other Packages diff --git a/docs/linting/Legacy_ESLint_Setup.mdx b/docs/getting-started/Legacy_ESLint_Setup.mdx similarity index 93% rename from docs/linting/Legacy_ESLint_Setup.mdx rename to docs/getting-started/Legacy_ESLint_Setup.mdx index 9a9b5a21db46..03bcc3578e3d 100644 --- a/docs/linting/Legacy_ESLint_Setup.mdx +++ b/docs/getting-started/Legacy_ESLint_Setup.mdx @@ -9,7 +9,7 @@ These steps will get you running ESLint with our recommended rules on your TypeS :::note This page is for [ESLint's legacy config format](https://eslint.org/docs/latest/use/configure/configuration-files). -See [Getting Started](../Getting_Started.mdx) for [ESLint's new "flat" configuration format](https://eslint.org/docs/latest/use/configure/configuration-files-new). +See [Getting Started](../getting-started/Quickstart) for [ESLint's new "flat" configuration format](https://eslint.org/docs/latest/use/configure/configuration-files-new). ::: ### Step 1: Installation @@ -83,7 +83,7 @@ ESLint will lint all TypeScript compatible files within the current folder, and 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.mdx). +If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx). ### Documentation Resources diff --git a/docs/Getting_Started.mdx b/docs/getting-started/Quickstart.mdx similarity index 51% rename from docs/Getting_Started.mdx rename to docs/getting-started/Quickstart.mdx index e64cdb025307..6517b680139f 100644 --- a/docs/Getting_Started.mdx +++ b/docs/getting-started/Quickstart.mdx @@ -1,20 +1,25 @@ --- -id: getting-started +id: quickstart title: Getting Started +slug: /getting-started/ +pagination_next: getting-started/typed-linting --- -## Quickstart +:::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. -These steps will get you running ESLint with our recommended rules on your TypeScript code as quickly 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). -:::note -This page is for [ESLint's new "flat" config format](https://eslint.org/docs/latest/use/configure/configuration-files-new). -See [Legacy ESLint Setup](./linting/Legacy_ESLint_Setup.mdx) for [ESLint's legacy format](https://eslint.org/docs/latest/use/configure/configuration-files). ::: +## 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 this plugin: +First, install the required packages for [ESLint](https://eslint.org), [TypeScript](https://typescriptlang.org), and [our tooling](../packages/TypeScript_ESLint.mdx): ```bash npm2yarn npm install --save-dev eslint typescript typescript-eslint @@ -22,7 +27,7 @@ npm install --save-dev eslint typescript typescript-eslint ### Step 2: Configuration -Next, create a `eslint.config.js` config file in the root of your project, and populate it with the following: +Next, create an `eslint.config.js` config file in the root of your project, and populate it with the following: ```js title="eslint.config.js" // @ts-check @@ -36,6 +41,8 @@ export default tseslint.config( ); ``` +This code will enable our recommended configuration for linting + ### Step 3: Running ESLint Open a terminal to the root of your project and run the following command: @@ -68,19 +75,20 @@ ESLint will lint all TypeScript compatible files within the current folder, and ## Details -The [`config`](./packages/TypeScript_ESLint.mdx) helper sets three parts of ESLint: +- `tseslint.config(...)` is an _optional_ helper function — [read more about it here](../packages/TypeScript_ESLint.mdx#config). +- `'@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). -- [Parser](https://eslint.org/docs/latest/use/configure/parser): set to [`@typescript-eslint/parser`](./packages/Parser.mdx) so ESLint knows how to parse the new pieces of TypeScript syntax. -- [Plugins](https://eslint.org/docs/latest/use/configure/plugins): set to [`@typescript-eslint/eslint-plugin`](./packages/ESLint_Plugin.mdx) to load [rules listed in our _Rules_ page](/rules). -- [Rules](https://eslint.org/docs/latest/use/configure/rules): extends from our [recommended configuration](./linting/Configurations.mdx#recommended) to enable our most commonly useful lint rules. - -See [ESLint's Configuration Files docs](https://eslint.org/docs/user-guide/configuring/configuration-files) for more details on configuring ESLint. +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. [Visit the next page for a setup guide](./linting/Typed_Linting.mdx 'Visit the next page for a typed rules setup guide'). +We provide a plethora of powerful rules that utilize the power of TypeScript's type information. + +[Visit the next] +[Visit the next page for a setup guide](./Typed_Linting.mdx 'Visit the next page for a typed rules setup guide'). -If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](./linting/Troubleshooting.mdx). +If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx). ### Documentation Resources diff --git a/docs/linting/Typed_Linting.mdx b/docs/getting-started/Typed_Linting.mdx similarity index 87% rename from docs/linting/Typed_Linting.mdx rename to docs/getting-started/Typed_Linting.mdx index 88e526242bc1..4de4516968c3 100644 --- a/docs/linting/Typed_Linting.mdx +++ b/docs/getting-started/Typed_Linting.mdx @@ -1,6 +1,7 @@ --- id: typed-linting title: Linting with Type Information +pagination_next: getting-started/typed-linting/monorepos --- import Tabs from '@theme/Tabs'; @@ -38,7 +39,7 @@ 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](./Configurations.mdx) we provide. This one contains recommended rules that additionally require type information. +- `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). @@ -69,7 +70,7 @@ module.exports = { In more detail: -- `plugin:@typescript-eslint/recommended-type-checked` is another [recommended configuration](./Configurations.mdx) we provide. This one contains recommended rules that additionally require type information. +- `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). - `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory (see [Parser#tsconfigRootDir](../packages/Parser.mdx#tsconfigrootdir)). @@ -79,7 +80,7 @@ In more detail: :::caution Your ESLint config file may start receiving a parsing error about type information. -See [our TSConfig inclusion FAQ](./Troubleshooting.mdx#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). +See [our TSConfig inclusion FAQ](../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). ::: With that done, run the same lint command you ran before. @@ -137,7 +138,7 @@ If your project is a multi-package monorepo, see [our docs on configuring a mono ### 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`](./Configurations.mdx#disable-type-checked) config to turn off type-aware linting on specific subsets 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. @@ -211,8 +212,8 @@ This means that generally they usually only run a complete lint before a push, o ### 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.mdx#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). +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.mdx). +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/linting/typed-linting/Monorepos.mdx b/docs/getting-started/typed-linting/Monorepos.mdx similarity index 98% rename from docs/linting/typed-linting/Monorepos.mdx rename to docs/getting-started/typed-linting/Monorepos.mdx index e58acd0a560b..13e8f8575626 100644 --- a/docs/linting/typed-linting/Monorepos.mdx +++ b/docs/getting-started/typed-linting/Monorepos.mdx @@ -1,6 +1,7 @@ --- id: monorepos title: Monorepo Configuration +pagination_next: null --- import Tabs from '@theme/Tabs'; @@ -158,4 +159,4 @@ As an interim workaround, consider one of the following: ## Troubleshooting -If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](../Troubleshooting.mdx). +If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](../../troubleshooting/FAQ.mdx). diff --git a/docs/maintenance/Issues.mdx b/docs/maintenance/Issues.mdx index a0f38da60b38..525147f88c54 100644 --- a/docs/maintenance/Issues.mdx +++ b/docs/maintenance/Issues.mdx @@ -141,7 +141,7 @@ We avoid features that: - Are only relevant for a minority of users, as they aren't likely worth the maintenance burden - Aren't TypeScript-specific (e.g. should be in ESLint core instead) - Are only relevant with specific userland frameworks or libraries, such as Jest or React -- Are for "formatting" functionality (we [strongly recommend users use a separate dedicated formatter](../linting/troubleshooting/Formatting.mdx)) +- Are for "formatting" functionality (we [strongly recommend users use a separate dedicated formatter](../troubleshooting/Formatting.mdx)) #### ✨ Rule Enhancements diff --git a/docs/maintenance/Team.mdx b/docs/maintenance/Team.mdx index 3fd2d66d8a80..6091e3e6a02a 100644 --- a/docs/maintenance/Team.mdx +++ b/docs/maintenance/Team.mdx @@ -94,5 +94,5 @@ We're eternally grateful to every individual and organization able to help us ke See [`.github/SPONSORSHIPS.md`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/SPONSORSHIPS.md) for documentation on how and why to sponsor us. -You can find our biggest sponsors on [typescript-eslint.io > Financial Contributors](https://typescript-eslint.io/#financial-contributors). +You can find our biggest sponsors on [typescript-eslint.io > Financial Contributors](/#financial-contributors). More can be found on [our Open Collective](https://opencollective.com/typescript-eslint). diff --git a/docs/packages/ESLint_Plugin.mdx b/docs/packages/ESLint_Plugin.mdx index 6db78ddfcebe..061606e3e05d 100644 --- a/docs/packages/ESLint_Plugin.mdx +++ b/docs/packages/ESLint_Plugin.mdx @@ -8,7 +8,7 @@ sidebar_label: eslint-plugin > The TypeScript plugin for ESLint. ✨ :::info -See [Getting Started](../Getting_Started.mdx) for documentation on how to lint your TypeScript code with ESLint. +See [Getting Started](../getting-started/Quickstart) for documentation on how to lint your TypeScript code with ESLint. ::: `@typescript-eslint/eslint-plugin` is an ESLint plugin used to load in custom rules and rule configurations lists from typescript-eslint. diff --git a/docs/packages/ESLint_Plugin_TSLint.mdx b/docs/packages/ESLint_Plugin_TSLint.mdx index 525b1c072477..61c9a05a2103 100644 --- a/docs/packages/ESLint_Plugin_TSLint.mdx +++ b/docs/packages/ESLint_Plugin_TSLint.mdx @@ -8,8 +8,8 @@ sidebar_label: eslint-plugin-tslint > ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. ✨ :::caution -Per [What About TSLint?](../linting/troubleshooting/TSLint.mdx), we highly recommend migrating off TSLint. -See [Getting Started](../Getting_Started.mdx) for documentation on how to lint your TypeScript code with ESLint. +Per [What About TSLint?](../troubleshooting/TSLint.mdx), we highly recommend migrating off TSLint. +See [Getting Started](../getting-started/Quickstart) for documentation on how to lint your TypeScript code with ESLint. ::: ## Installation diff --git a/docs/packages/Parser.mdx b/docs/packages/Parser.mdx index 062c7aa247a0..8d39a8fb0bdd 100644 --- a/docs/packages/Parser.mdx +++ b/docs/packages/Parser.mdx @@ -60,7 +60,7 @@ interface ParserOptions { Whether to use common heuristics to infer whether ESLint is being used as part of a single run (as opposed to `--fix` mode or in a persistent session such as an editor extension). -When typescript-eslint handles TypeScript Program management behind the scenes for [linting with type information](../linting/Typed_Linting.mdx), this distinction is important for performance. +When typescript-eslint handles TypeScript Program management behind the scenes for [linting with type information](../getting-started/Typed_Linting.mdx), this distinction is important for performance. There is significant overhead to managing TypeScript "Watch" Programs needed for the long-running use-case. Being able to assume the single run case allows typescript-eslint to faster immutable Programs instead. @@ -126,7 +126,7 @@ Specifies the version of ECMAScript syntax you want to use. This is used by the > Default `undefined`. -This option allow you to tell parser to act as if `emitDecoratorMetadata: true` is set in `tsconfig.json`, but without [type-aware linting](../linting/Typed_Linting.mdx). In other words, you don't have to specify `parserOptions.project` in this case, making the linting process faster. +This option allow you to tell parser to act as if `emitDecoratorMetadata: true` is set in `tsconfig.json`, but without [type-aware linting](../getting-started/Typed_Linting.mdx). In other words, you don't have to specify `parserOptions.project` in this case, making the linting process faster. ### `extraFileExtensions` diff --git a/docs/packages/TypeScript_ESLint.mdx b/docs/packages/TypeScript_ESLint.mdx index 5bd5e38c1f77..46675ee885af 100644 --- a/docs/packages/TypeScript_ESLint.mdx +++ b/docs/packages/TypeScript_ESLint.mdx @@ -11,12 +11,12 @@ This package is the main entrypoint that you can use to consume our tooling with This package exports the following: -| name | description | -| --------- | ---------------------------------------------------------- | -| `config` | A utility function for creating type-safe flat configs | -| `configs` | [Our eslint (flat) configs](../linting/Configurations.mdx) | -| `parser` | [Our parser](./Parser.mdx) | -| `plugin` | [Our plugin](./ESLint_Plugin.mdx) | +| name | description | +| --------- | --------------------------------------------------------------- | +| `config` | A utility function for creating type-safe flat configs | +| `configs` | [Our eslint (flat) configs](../users/Shared_Configurations.mdx) | +| `parser` | [Our parser](./Parser.mdx) | +| `plugin` | [Our plugin](./ESLint_Plugin.mdx) | ## Installation @@ -32,11 +32,11 @@ If you're migrating from a "legacy" `.eslintrc` configuration setup you likely h npm un @typescript-eslint/parser @typescript-eslint/eslint-plugin ``` -## Usage +For more information on migrating from a "legacy" config setup, see [ESLint's Configuration Migration Guide](https://eslint.org/docs/latest/use/configure/migration-guide). -The `config` function is a simple utility which does a few things. First and foremost it is a strictly typed function - meaning it allows you to write type-safe configs! +## Usage -The simplest usage would be: +The simplest usage of this package would be: ```js title="eslint.config.js" // @ts-check @@ -50,31 +50,52 @@ export default tseslint.config( ); ``` +This config file exports a flat config that enables both the [core eslint recommended config](https://www.npmjs.com/package/@eslint/js) and [our recommended config](../users/Shared_Configurations.mdx#recommended). + +For more information on the `tseslint.config` function [see below](#config). + +### Advanced usage + You can also declare our plugin and parser in your config via this package. For example this config would enable our plugin, our parser, and type-aware linting with a few of our popular type-aware rules: ```js title="eslint.config.js" // @ts-check +import eslint from '@eslint/js'; +import importPlugin from 'eslint-plugin-import'; import tseslint from 'typescript-eslint'; -export default tseslint.config({ - plugins: { - '@typescript-eslint': tseslint.plugin, +export default tseslint.config( + { + // config with just ignores is the replacement for `.eslintignore` + ignores: ['**/build/**', '**/dist/**', 'src/some/file/to/ignore.ts'], }, - languageOptions: { - parser: tseslint.parser, - parserOptions: { - project: true, + eslint.configs.recommended, + { + plugins: { + '@typescript-eslint': tseslint.plugin, + jest: jestPlugin, + }, + languageOptions: { + parser: tseslint.parser, + parserOptions: { + project: true, + }, + }, + rules: { + '@typescript-eslint/no-unsafe-argument': 'error', + '@typescript-eslint/no-unsafe-assignment': 'error', + '@typescript-eslint/no-unsafe-call': 'error', + '@typescript-eslint/no-unsafe-member-access': 'error', + '@typescript-eslint/no-unsafe-return': 'error', }, }, - rules: { - '@typescript-eslint/no-unsafe-argument': 'error', - '@typescript-eslint/no-unsafe-assignment': 'error', - '@typescript-eslint/no-unsafe-call': 'error', - '@typescript-eslint/no-unsafe-member-access': 'error', - '@typescript-eslint/no-unsafe-return': 'error', + { + // disable type-aware linting on JS files + files: ['**/*.js'], + ...tseslint.configs.disableTypeChecked, }, -}); +); ``` :::warning @@ -83,6 +104,56 @@ We **_strongly_** recommend declaring our plugin with the namespace `@typescript You may choose a different namespace - but note that currently [flat configs allow the same plugin to be registered, configured, and have duplicate reports under multiple namespaces](https://github.com/eslint/eslint/discussions/17766). ::: +## `config(...)` + +The `config` function is a [variadic](https://en.wikipedia.org/wiki/Variadic_function) [identity function](https://en.wikipedia.org/wiki/Identity_function) which is a fancy way of saying that it's a function that takes `1..n` inputs and returns the inputs unchanged. It can be used to quickly and easily provide types for your flat config file. By using this function you will get autocomplete and documentation for all config properties in addition to TypeScript errors should you provide invalid values. + + + + +```ts title="eslint.config.js" +// @ts-check + +import eslint from '@eslint/js'; +import tseslint from 'typescript-eslint'; + +export default tseslint.config( + eslint.configs.recommended, + ...tseslint.configs.recommended, + { + /*... */ + }, + // ... +); +``` + + + + +```ts title="eslint.config.js" +// @ts-check + +import eslint from '@eslint/js'; +import tseslint from 'typescript-eslint'; + +/** @type {import('typescript-eslint').Config} */ +export default [ + eslint.configs.recommended, + ...tseslint.configs.recommended, + { + /*... */ + }, + // ... +]; +``` + + + + +:::note +We _**strongly**_ recommend using this utility to improve the config authoring experience — however it is entirely optional and choosing not to use it will not impact your ability to use our tooling; you'll just need to manually adjust any examples as appropriate. +::: + ### Flat config `extends` The `tseslint.config` utility function also adds handling for the `extends` property on flat config objects. This allows you to more easily extend shared configs for specific file patterns whilst also overriding rules/options provided by those configs: @@ -120,10 +191,10 @@ export default [ ]; ``` -We found that this is a pretty common operation when writing ESLint configs which is why we provided this convenience property - for example in codebases with type-aware linting a config object like this is a very common way to disable TS-specific linting setups on JS files: +We found that this is a pretty common operation when writing ESLint configs which is why we provided this convenience property. For example in codebases with type-aware linting a config object like this is a very common way to disable TS-specific linting setups on JS files: ```js -export default [ +export default tseslint.config([ { files: ['**/*.js'], extends: [tseslint.configs.disableTypeChecked], @@ -136,5 +207,5 @@ export default [ '@typescript-eslint/explicit-function-return-type': 'off', }, }, -]; +]); ``` diff --git a/docs/linting/Troubleshooting.mdx b/docs/troubleshooting/FAQ.mdx similarity index 80% rename from docs/linting/Troubleshooting.mdx rename to docs/troubleshooting/FAQ.mdx index 36d8798ceab3..eb50ddb23f8c 100644 --- a/docs/linting/Troubleshooting.mdx +++ b/docs/troubleshooting/FAQ.mdx @@ -1,6 +1,7 @@ --- -id: troubleshooting -title: Troubleshooting & FAQs +id: faqs +title: FAQs +slug: /troubleshooting/ --- ## I am using a rule from ESLint core, and it doesn't work correctly with TypeScript code @@ -39,55 +40,47 @@ These errors are caused by an ESLint config requesting type information be gener - 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. - If you **do** want to lint the file: - - If you **do not** want to lint the file with [type-aware linting](./Typed_Linting.mdx): - - Use [ESLint's `overrides` configuration](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#configuration-based-on-glob-patterns) to configure the file to not be parsed with type information: -
- - A popular setup is to remove all rules requiring type information from the top-level configuration - and only apply them to TypeScript files via an override. - - - ```js title=".eslintrc.cjs" - module.exports = { - // ... the rest of your config ... - overrides: [ - { - extends: [ - 'plugin:@typescript-eslint/recommended-requiring-type-checking', - ], - files: ['./**/*.{ts,tsx}'], - }, - ], - }; - ``` - -
-
- - Alternatively, in our version v6, you can use our{' '} - disable-type-checked config to disable type checking for just that type of file. - - - ```js title=".eslintrc.cjs" - module.exports = { - // ... the rest of your config ... - overrides: [ - { - extends: ['plugin:@typescript-eslint/disable-type-checked'], - files: ['./**/*.js'], - }, - ], - }; - ``` - To disable type checking for files manually, set `parserOptions: { project: null }` to an override for the files you wish to exclude. Note that `{ project: undefined }` will not work, and you'll also need to disable any rules or rule options that require type checking. -
- - - If you **do** want to lint the file with [type-aware linting](./Typed_Linting.mdx): + - 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. + - 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) - - [`.eslintrc.js`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.eslintrc.js) + - [`eslint.config.mjs`](https://github.com/typescript-eslint/typescript-eslint/blob/main/eslint.config.mjs) @@ -105,12 +98,12 @@ However, if no specified TSConfig includes the source file, the parser won't be This error most commonly happens on config files or similar that are not included in their project TSConfig(s). For example, many projects have files like: -- An `.eslintrc.cjs` with `parserOptions.project: ["./tsconfig.json"]` +- An `.eslintrc.cjs` / `eslint.config.js` with `parserOptions.project: ["./tsconfig.json"]` - A `tsconfig.json` with `include: ["src"]` -In that case, viewing the `.eslintrc.cjs` in an IDE with the ESLint extension will show the error notice that the file couldn't be linted because it isn't included in `tsconfig.json`. +In that case, viewing the file in an IDE with the ESLint extension will show the error notice that the file couldn't be linted because it isn't included in `tsconfig.json`. -See our docs on [type aware linting](./Typed_Linting.mdx) for more information. +See our docs on [type aware linting](../getting-started/Typed_Linting.mdx) for more information. ## I get errors telling me "The file must be included in at least one of the projects provided" @@ -121,7 +114,7 @@ Update to the latest version to see a more informative version of this error mes First make sure you've read the docs and understand ESLint configuration files: -- [Read our getting started guide](../Getting_Started.mdx) to ensure your config is properly setup to start configuring our rules. +- [Read our getting started guide](./getting-started/Quickstart) to ensure your config is properly setup to start configuring our rules. - [Checkout ESLint's documentation on configuring rules](https://eslint.org/docs/latest/use/configure/rules) to ensure you understand how to configure rules. Our [rule docs](/rules) detail the options each rule supports under the "Options" heading. @@ -142,8 +135,29 @@ type RuleConfig = Some examples -```js title=".eslintrc.js" + + + +```js title="eslint.config.js" +export default tseslint.config( + // ... the rest of your config ... + { + rules: { + // turns a rule on with no configuration (i.e. uses the default configuration) + '@typescript-eslint/array-type': 'error', + // turns on a rule with configuration + '@typescript-eslint/no-explicit-any': ['warn', { ignoreRestArgs: true }], + }, + }, +); +``` + + + + +```js title=".eslintrc.cjs" module.exports = { + // ... the rest of your config ... rules: { // turns a rule on with no configuration (i.e. uses the default configuration) '@typescript-eslint/array-type': 'error', @@ -153,6 +167,9 @@ module.exports = { }; ``` + + + ## typescript-eslint thinks my variable is never nullish / is `any` / etc., but that is clearly not the case to me Our type-aware rules almost always trust the type information provided by the TypeScript compiler. Therefore, an easy way to check if our rule is behaving correctly is to inspect the type of the variable in question, such as by hovering over it in your IDE. @@ -180,7 +197,7 @@ If the IDE provides different type information from typescript-eslint's report, You can use it, but it will only work reliably for untyped rules -- and even then, not always. Any ESLint rule that checks logic across files, including many rules from `eslint-plugin-import`, creates cross-file dependencies. -[Typed lint rules](./Typed_Linting.mdx) almost always have dependencies on types across files in practice. +[Typed lint rules](../getting-started/Typed_Linting.mdx) almost always have dependencies on types across files in practice. ESLint's caching doesn't account for those cross-file dependencies. We don't recommend using `--cache`. @@ -189,8 +206,31 @@ We don't recommend using `--cache`. You can use `parserOptions.extraFileExtensions` to specify an array of non-TypeScript extensions to allow, for example: + + + +```js title="eslint.config.js" +export default tseslint.config( + // ... the rest of your config ... + { + languageOptions: { + parserOptions: { + tsconfigRootDir: import.meta.dirname, + project: ['./tsconfig.json'], + // Add this line + extraFileExtensions: ['.vue'], + }, + }, + }, +); +``` + + + + ```js title=".eslintrc.js" module.exports = { + // ... the rest of your config ... parserOptions: { tsconfigRootDir: __dirname, project: ['./tsconfig.json'], @@ -200,19 +240,60 @@ module.exports = { }; ``` + + + ## I am running into errors when parsing TypeScript in my .vue files If you are running into issues parsing .vue files, it might be because parsers like [`vue-eslint-parser`](https://www.npmjs.com/package/vue-eslint-parser) are required to parse `.vue` files. In this case you can move `@typescript-eslint/parser` inside `parserOptions` and use `vue-eslint-parser` as the top level parser. -```diff -- "parser": "@typescript-eslint/parser", -+ "parser": "vue-eslint-parser", - "parserOptions": { -+ "parser": "@typescript-eslint/parser", - "sourceType": "module" - } + + + +```js title="eslint.config.js" +import tseslint from 'typescript-eslint'; +// Add this line +import vueParser from 'vue-eslint-parser'; + +export default tseslint.config( + // ... the rest of your config ... + { + languageOptions: { + // Remove this line + parser: tseslint.parser, + // Add this line + parser: vueParser, + parserOptions: { + // Add this line + parser: tseslint.parser, + sourceType: 'module', + }, + }, + }, +); +``` + + + + +```js title=".eslintrc.js" +module.exports = { + // ... the rest of your config ... + // Remove this line + parser: '@typescript-eslint/parser', + // Add this line + parser: 'vue-eslint-parser', + parserOptions: { + parser: '@typescript-eslint/parser', + // Add this line + extraFileExtensions: ['.vue'], + }, +}; ``` + + + The `parserOptions.parser` option can also specify an object to specify multiple parsers. See the [`vue-eslint-parser` usage guide](https://eslint.vuejs.org/user-guide/#usage) for more details. ## One of my lint rules isn't working correctly on a pure JavaScript file @@ -291,9 +372,29 @@ As of our v4.0.0 release, this also applies to types. If you use global types from a 3rd party package (i.e. anything from an `@types` package), then you will have to configure ESLint appropriately to define these global types. For example; the `JSX` namespace from `@types/react` is a global 3rd party type that you must define in your ESLint config. -Note, that for a mixed project including JavaScript and TypeScript, the `no-undef` rule (like any rule) can be turned off for TypeScript files alone by adding an `overrides` section to `.eslintrc.cjs`: +Note, that for a mixed project including JavaScript and TypeScript, the `no-undef` rule (like any rule) can be turned off for TypeScript files alone as follows: -```js title=".eslintrc.cjs" + + + +```js title="eslint.config.js" +import tseslint from 'typescript-eslint'; + +export default tseslint.config( + // ... the rest of your config ... + { + files: ['**/*.{ts,tsx,mts,cts}'], + rules: { + 'no-undef': 'off', + }, + }, +); +``` + + + + +```js title=".eslintrc.js" module.exports = { // ... the rest of your config ... overrides: [ @@ -307,6 +408,9 @@ module.exports = { }; ``` + + + If you choose to leave on the ESLint `no-undef` lint rule, you can [manually define the set of allowed `globals` in your ESLint config](https://eslint.org/docs/user-guide/configuring/language-options#specifying-globals), and/or you can use one of the [pre-defined environment (`env`) configurations](https://eslint.org/docs/user-guide/configuring/language-options#specifying-environments). ## How do I check to see what versions are installed? @@ -384,11 +488,11 @@ For developers updating ESLint rules in plugins that still need to support types For more context, see the [Some properties named typeParameters instead of typeArguments](https://github.com/typescript-eslint/typescript-eslint/issues/146) issue, and the implementing [fix: rename typeParameters to typeArguments where needed](https://github.com/typescript-eslint/typescript-eslint/pull/5384) pull request. -The [typescript-eslint v6 release post](https://deploy-preview-6515--typescript-eslint.netlify.app/blog/announcing-typescript-eslint-v6-beta) has more information on typescript-eslint v6. +The [typescript-eslint v6 release post](/blog/announcing-typescript-eslint-v6-beta) has more information on typescript-eslint v6. ## My linting feels really slow -If you think you're having issues with performance, see our [Performance Troubleshooting documentation](./troubleshooting/Performance.mdx). +If you think you're having issues with performance, see our [Performance Troubleshooting documentation](../troubleshooting/Performance.mdx). ## Are TypeScript project references supported? diff --git a/docs/linting/troubleshooting/Formatting.mdx b/docs/troubleshooting/Formatting.mdx similarity index 89% rename from docs/linting/troubleshooting/Formatting.mdx rename to docs/troubleshooting/Formatting.mdx index 57d1562ebb72..0b7c15e0c631 100644 --- a/docs/linting/troubleshooting/Formatting.mdx +++ b/docs/troubleshooting/Formatting.mdx @@ -23,7 +23,7 @@ Additionally linters typically run each rule isolated from one another. This has - any two lint rules can't share config meaning one lint rule's fixer might introduce a violation of another lint rule's fixer (eg one lint rule might use the incorrect indentation character). - lint rule fixers can conflict (apply to the same code range), forcing the linter to perform an additional cycle to attempt to apply a fixer to a clean set of code. -These problems cause a linter to be much slower - which can be much more of a problem in projects that enable [typed linting](../Typed_Linting.mdx). +These problems cause a linter to be much slower - which can be much more of a problem in projects that enable [typed linting](../getting-started/Typed_Linting.mdx). Formatting with a linter is also much less consistent and less able to handle edge-cases than a purpose-built formatter. The maintenance cost of formatting-related lint rules is typically very high as a result. @@ -40,6 +40,29 @@ You can then configure your formatter separately from ESLint. Using this config by adding it to the end of your `extends`: + + + +```js title="eslint.config.js" +// @ts-check + +import eslint from '@eslint/js'; +import someOtherConfig from 'eslint-config-other-configuration-that-enables-formatting-rules'; +import prettierConfig from 'eslint-config-prettier'; +import tseslint from 'typescript-eslint'; + +export default tseslint.config( + eslint.configs.recommended, + ...tseslint.configs.recommended, + ...someOtherConfig, + // Add this line + ...prettierConfig, +); +``` + + + + ```js title=".eslintrc.js" /* eslint-env node */ module.exports = { @@ -56,6 +79,9 @@ module.exports = { }; ``` + + + Note that even if you use a formatter other than `prettier`, you can use `eslint-config-prettier` as it exclusively turns **off** all formatting rules. #### `eslint-plugin-prettier` @@ -65,7 +91,7 @@ Note that even if you use a formatter other than `prettier`, you can use `eslint - The _config_ only disables rules from core and other plugins. - The _plugin_ loads and runs Prettier inside ESLint. -Running Prettier inside ESLint can be slow: see [Performance Troubleshooting > `eslint-plugin-prettier`](./performance-troubleshooting#eslint-plugin-prettier). +Running Prettier inside ESLint can be slow: see [Performance Troubleshooting > `eslint-plugin-prettier`](./Performance.mdx#eslint-plugin-prettier). However, because it doesn't re-implement Prettier's logic in ESLint, the caveats mentioned about using linters for formatting don't apply to `eslint-plugin-prettier` either. ## ESLint Core and Formatting diff --git a/docs/linting/troubleshooting/Performance.mdx b/docs/troubleshooting/Performance.mdx similarity index 88% rename from docs/linting/troubleshooting/Performance.mdx rename to docs/troubleshooting/Performance.mdx index 71523c0db210..490b6c0ce650 100644 --- a/docs/linting/troubleshooting/Performance.mdx +++ b/docs/troubleshooting/Performance.mdx @@ -3,7 +3,7 @@ id: performance-troubleshooting title: Performance Troubleshooting --- -As mentioned in the [type-aware linting doc](../Typed_Linting.mdx), if you're using type-aware linting, your lint times should be roughly the same as your build times. +As mentioned in the [type-aware linting doc](../getting-started/Typed_Linting.mdx), if you're using type-aware linting, your lint times should be roughly the same as your build times. If you're experiencing times much slower than that, then there are a few common culprits. @@ -23,11 +23,39 @@ Always ensure you provide globs targeted at the folders you are specifically wan Specifying `tsconfig.json` paths in your ESLint commands is also likely to cause much more disk IO than expected. Instead of globs that use `**` to recursively check all folders, prefer paths that use a single `*` at a time. + + + +```js title="eslint.config.js" +// @ts-check + +import eslint from '@eslint/js'; +import tseslint from 'typescript-eslint'; + +export default tseslint.config( + eslint.configs.recommended, + ...tseslint.configs.recommendedRequiringTypeChecking, + { + languageOptions: { + parserOptions: { + tsconfigRootDir: import.meta.dirname, + // Remove this line + project: ['./**/tsconfig.json'], + // Add this line + project: ['./packages/*/tsconfig.json'], + }, + }, + }, +); +``` + + + + ```js title=".eslintrc.js" module.exports = { extends: [ 'eslint:recommended', - 'plugin:@typescript-eslint/recommended', 'plugin:@typescript-eslint/recommended-requiring-type-checking', ], parser: '@typescript-eslint/parser', @@ -43,6 +71,9 @@ module.exports = { }; ``` + + + See [Glob pattern in parser's option "project" slows down linting](https://github.com/typescript-eslint/typescript-eslint/issues/2611) for more details. ## The `indent` / `@typescript-eslint/indent` rules @@ -85,7 +116,7 @@ We recommend you do not use the following rules, as TypeScript provides the same - `import/namespace` - `import/default` - `import/no-named-as-default-member` -- `import/no-unresolved` (as long as you are using [`import` over `require`](https://typescript-eslint.io/rules/no-var-requires/)) +- `import/no-unresolved` (as long as you are using [`import` over `require`](/rules/no-var-requires/)) The following rules do not have equivalent checks in TypeScript, so we recommend that you only run them at CI/push time, to lessen the local performance burden. diff --git a/docs/linting/troubleshooting/TSLint.mdx b/docs/troubleshooting/TSLint.mdx similarity index 97% rename from docs/linting/troubleshooting/TSLint.mdx rename to docs/troubleshooting/TSLint.mdx index 29e778aec936..1c595ac7c8a8 100644 --- a/docs/linting/troubleshooting/TSLint.mdx +++ b/docs/troubleshooting/TSLint.mdx @@ -17,7 +17,7 @@ You can look at [the alternatives list](https://github.com/typescript-eslint/typ There is also the ultimate fallback option of using both linters together for a while during your transition if you absolutely have to by using TSLint _within_ ESLint. -For this option, check out [`@typescript-eslint/eslint-plugin-tslint`](../../packages/ESLint_Plugin_TSLint.mdx). +For this option, check out [`@typescript-eslint/eslint-plugin-tslint`](../packages/ESLint_Plugin_TSLint.mdx). ## Why Deprecate TSLint? diff --git a/docs/users/Releases.mdx b/docs/users/Releases.mdx index 4ad0fdd9db70..09070f950ecb 100644 --- a/docs/users/Releases.mdx +++ b/docs/users/Releases.mdx @@ -50,22 +50,10 @@ During these periods, we manually publish `canary` releases until we are happy w To try out the latest canary versions of typescript-eslint, install `@typescript-eslint/eslint-plugin@canary` and `@typescript-eslint/parser@canary`. Note that npm may need a `--force` to override version requirements. - - -### npm - -```bash +```bash npm2yarn npm i @typescript-eslint/eslint-plugin@canary @typescript-eslint/parser@canary --save-dev --force ``` -### Yarn - -```bash -yarn add @typescript-eslint/eslint-plugin@canary @typescript-eslint/parser@canary --dev -``` - - - ## Major Releases We currently do not have a set schedule around when major releases shall be performed; instead they are done as the need arises. diff --git a/docs/linting/Configurations.mdx b/docs/users/Shared_Configurations.mdx similarity index 95% rename from docs/linting/Configurations.mdx rename to docs/users/Shared_Configurations.mdx index 7d997c3d5a88..03cb635d0cb8 100644 --- a/docs/linting/Configurations.mdx +++ b/docs/users/Shared_Configurations.mdx @@ -1,6 +1,6 @@ --- id: configs -title: Configurations +title: Shared Configs --- import Tabs from '@theme/Tabs'; @@ -16,7 +16,7 @@ import TabItem from '@theme/TabItem'; ### Projects Without Type Checking -If your project does not enable [typed linting](./Typed_Linting.mdx), we suggest enabling the [`recommended`](#recommended) and [`stylistic`](#stylistic) configurations to start: +If your project does not enable [typed linting](../getting-started/Typed_Linting.mdx), we suggest enabling the [`recommended`](#recommended) and [`stylistic`](#stylistic) configurations to start: @@ -49,7 +49,7 @@ module.exports = { ### Projects With Type Checking -If your project enables [typed linting](./Typed_Linting.mdx), we suggest enabling the [`recommended-type-checked`](#recommended-type-checked) and [`stylistic-type-checked`](#stylistic-type-checked) configurations to start: +If your project enables [typed linting](../getting-started/Typed_Linting.mdx), we suggest enabling the [`recommended-type-checked`](#recommended-type-checked) and [`stylistic-type-checked`](#stylistic-type-checked) configurations to start: @@ -398,4 +398,4 @@ If you feel strongly that a specific rule should (or should not) be one of these None of the preset configs provided by typescript-eslint enable formatting rules (rules that only serve to enforce code whitespace and other trivia). We strongly recommend you use Prettier or an equivalent for formatting your code, not ESLint formatting rules. -See [What About Formatting? > Suggested Usage](./troubleshooting/Formatting.mdx#suggested-usage---prettier). +See [What About Formatting? > Suggested Usage](../troubleshooting/Formatting.mdx#suggested-usage---prettier). diff --git a/packages/typescript-eslint/src/index.ts b/packages/typescript-eslint/src/index.ts index ad8487db5848..4f1b55c4ea64 100644 --- a/packages/typescript-eslint/src/index.ts +++ b/packages/typescript-eslint/src/index.ts @@ -25,20 +25,66 @@ const plugin: TSESLint.FlatConfig.Plugin = { rules: pluginBase.rules, }; -export = { +const configs = { + all: allConfig(plugin, parser), + base: baseConfig(plugin, parser), + disableTypeChecked: disableTypeCheckedConfig(plugin, parser), + eslintRecommended: eslintRecommendedConfig(plugin, parser), + recommended: recommendedConfig(plugin, parser), + recommendedTypeChecked: recommendedTypeCheckedConfig(plugin, parser), + strict: strictConfig(plugin, parser), + strictTypeChecked: strictTypeCheckedConfig(plugin, parser), + stylistic: stylisticConfig(plugin, parser), + stylisticTypeChecked: stylisticTypeCheckedConfig(plugin, parser), +}; + +export type Config = TSESLint.FlatConfig.ConfigFile; +/* +eslint-disable-next-line import/no-default-export -- +we do both a default and named exports to allow people to use this package from +both CJS and ESM in very natural ways. + +EG it means that all of the following are valid: + +```ts +import tseslint from 'typescript-eslint'; + +export default tseslint.config( + ...tseslint.configs.recommended, +); +``` +```ts +import { config, parser, plugin } from 'typescript-eslint'; + +export default config( + { + languageOptions: { parser } + plugins: { ts: plugin }, + } +); +``` +```ts +const tseslint = require('typescript-eslint'); + +module.exports = tseslint.config( + ...tseslint.configs.recommended, +); +``` +```ts +const { config, parser, plugin } = require('typescript-eslint'); + +module.exports = config( + { + languageOptions: { parser } + plugins: { ts: plugin }, + } +); +``` +*/ +export default { config, - configs: { - all: allConfig(plugin, parser), - base: baseConfig(plugin, parser), - disableTypeChecked: disableTypeCheckedConfig(plugin, parser), - eslintRecommended: eslintRecommendedConfig(plugin, parser), - recommended: recommendedConfig(plugin, parser), - recommendedTypeChecked: recommendedTypeCheckedConfig(plugin, parser), - strict: strictConfig(plugin, parser), - strictTypeChecked: strictTypeCheckedConfig(plugin, parser), - stylistic: stylisticConfig(plugin, parser), - stylisticTypeChecked: stylisticTypeCheckedConfig(plugin, parser), - }, + configs, parser, plugin, }; +export { config, configs, parser, plugin }; diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index b94a12c33660..1dedb8b220be 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -6,35 +6,41 @@ module.exports = { collapsible: false, items: [ { - collapsible: false, - items: ['linting/typed-linting/monorepos'], - label: 'Linting with Type Information', - link: { - id: 'linting/typed-linting', - type: 'doc', - }, - type: 'category', + label: 'Quickstart', + id: 'getting-started/quickstart', + type: 'doc', }, - 'linting/configs', { collapsible: false, - items: [ - 'linting/troubleshooting/performance-troubleshooting', - 'linting/troubleshooting/formatting', - 'linting/troubleshooting/tslint', - ], - label: 'Troubleshooting & FAQs', + items: ['getting-started/typed-linting/monorepos'], + label: 'Linting with Type Information', link: { - id: 'linting/troubleshooting', + id: 'getting-started/typed-linting', type: 'doc', }, type: 'category', }, - 'linting/legacy-eslint-setup', + 'getting-started/legacy-eslint-setup', ], label: 'Getting Started', link: { - id: 'getting-started', + id: 'getting-started/quickstart', + type: 'doc', + }, + type: 'category', + }, + + { + collapsible: false, + items: [ + 'troubleshooting/faqs', + 'troubleshooting/performance-troubleshooting', + 'troubleshooting/formatting', + 'troubleshooting/tslint', + ], + label: 'Troubleshooting & FAQs', + link: { + id: 'troubleshooting/faqs', type: 'doc', }, type: 'category', @@ -42,6 +48,12 @@ module.exports = { { collapsible: false, items: [ + { + label: 'Rules', + href: '/rules/', + type: 'link', + }, + 'users/configs', 'users/dependency-versions', 'users/releases', 'users/versioning', From fa8583c137505ff7a29f78d07de8b31da5c1a0ee Mon Sep 17 00:00:00 2001 From: Brad Zacher Date: Mon, 19 Feb 2024 20:32:15 +1030 Subject: [PATCH 2/3] fix netlify build --- docs/getting-started/Legacy_ESLint_Setup.mdx | 5 ++- docs/getting-started/Quickstart.mdx | 3 ++ docs/packages/ESLint_Plugin.mdx | 2 +- docs/packages/ESLint_Plugin_TSLint.mdx | 2 +- docs/packages/TypeScript_ESLint.mdx | 3 ++ docs/troubleshooting/FAQ.mdx | 5 ++- docs/troubleshooting/Formatting.mdx | 3 ++ docs/troubleshooting/Performance.mdx | 3 ++ packages/eslint-plugin/docs/rules/README.md | 8 ++--- .../docs/rules/consistent-type-imports.md | 2 +- .../eslint-plugin/docs/rules/no-extra-semi.md | 2 +- .../eslint-plugin/docs/rules/no-type-alias.md | 2 +- packages/eslint-plugin/src/configs/all.ts | 2 +- .../src/configs/disable-type-checked.ts | 2 +- .../src/configs/recommended-type-checked.ts | 2 +- .../eslint-plugin/src/configs/recommended.ts | 2 +- .../src/configs/strict-type-checked.ts | 2 +- packages/eslint-plugin/src/configs/strict.ts | 2 +- .../src/configs/stylistic-type-checked.ts | 2 +- .../eslint-plugin/src/configs/stylistic.ts | 2 +- packages/repo-tools/src/generate-configs.mts | 2 +- packages/typescript-eslint/src/configs/all.ts | 2 +- .../src/configs/disable-type-checked.ts | 2 +- .../src/configs/recommended-type-checked.ts | 2 +- .../src/configs/recommended.ts | 2 +- .../src/configs/strict-type-checked.ts | 2 +- .../typescript-eslint/src/configs/strict.ts | 2 +- .../src/configs/stylistic-type-checked.ts | 2 +- .../src/configs/stylistic.ts | 2 +- ...13-announcing-typescript-eslint-v6-beta.md | 19 +++++----- ...3-07-09-announcing-typescript-eslint-v6.md | 18 +++++----- .../2023-09-18-parser-options-project-true.md | 6 ++-- ...2023-12-25-deprecating-formatting-rules.md | 4 +-- packages/website/docusaurusConfig.ts | 35 +++++++++++++++++++ packages/website/package.json | 1 + .../insertions/insertWhenNotToUseIt.ts | 4 +-- .../theme/MDXComponents/RuleAttributes.tsx | 4 +-- yarn.lock | 21 +++++++++++ 38 files changed, 130 insertions(+), 56 deletions(-) diff --git a/docs/getting-started/Legacy_ESLint_Setup.mdx b/docs/getting-started/Legacy_ESLint_Setup.mdx index 03bcc3578e3d..c6dd1dbd70da 100644 --- a/docs/getting-started/Legacy_ESLint_Setup.mdx +++ b/docs/getting-started/Legacy_ESLint_Setup.mdx @@ -3,13 +3,16 @@ id: legacy-eslint-setup title: Legacy ESLint Setup --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## Quickstart These steps will get you running ESLint with our recommended rules on your TypeScript code as quickly as possible. :::note This page is for [ESLint's legacy config format](https://eslint.org/docs/latest/use/configure/configuration-files). -See [Getting Started](../getting-started/Quickstart) for [ESLint's new "flat" configuration format](https://eslint.org/docs/latest/use/configure/configuration-files-new). +See [Getting Started](../getting-started/Quickstart.mdx) for [ESLint's new "flat" configuration format](https://eslint.org/docs/latest/use/configure/configuration-files-new). ::: ### Step 1: Installation diff --git a/docs/getting-started/Quickstart.mdx b/docs/getting-started/Quickstart.mdx index 6517b680139f..2a5a2fba75cc 100644 --- a/docs/getting-started/Quickstart.mdx +++ b/docs/getting-started/Quickstart.mdx @@ -5,6 +5,9 @@ slug: /getting-started/ pagination_next: getting-started/typed-linting --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + :::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. diff --git a/docs/packages/ESLint_Plugin.mdx b/docs/packages/ESLint_Plugin.mdx index 061606e3e05d..bf0777a005d3 100644 --- a/docs/packages/ESLint_Plugin.mdx +++ b/docs/packages/ESLint_Plugin.mdx @@ -8,7 +8,7 @@ sidebar_label: eslint-plugin > The TypeScript plugin for ESLint. ✨ :::info -See [Getting Started](../getting-started/Quickstart) for documentation on how to lint your TypeScript code with ESLint. +See [Getting Started](../getting-started/Quickstart.mdx) for documentation on how to lint your TypeScript code with ESLint. ::: `@typescript-eslint/eslint-plugin` is an ESLint plugin used to load in custom rules and rule configurations lists from typescript-eslint. diff --git a/docs/packages/ESLint_Plugin_TSLint.mdx b/docs/packages/ESLint_Plugin_TSLint.mdx index 61c9a05a2103..6b9da9e6982f 100644 --- a/docs/packages/ESLint_Plugin_TSLint.mdx +++ b/docs/packages/ESLint_Plugin_TSLint.mdx @@ -9,7 +9,7 @@ sidebar_label: eslint-plugin-tslint :::caution Per [What About TSLint?](../troubleshooting/TSLint.mdx), we highly recommend migrating off TSLint. -See [Getting Started](../getting-started/Quickstart) for documentation on how to lint your TypeScript code with ESLint. +See [Getting Started](../getting-started/Quickstart.mdx) for documentation on how to lint your TypeScript code with ESLint. ::: ## Installation diff --git a/docs/packages/TypeScript_ESLint.mdx b/docs/packages/TypeScript_ESLint.mdx index 46675ee885af..8ea449568e15 100644 --- a/docs/packages/TypeScript_ESLint.mdx +++ b/docs/packages/TypeScript_ESLint.mdx @@ -3,6 +3,9 @@ id: typescript-eslint sidebar_label: typescript-eslint --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # `typescript-eslint` > Tooling which enables you to use TypeScript with ESLint diff --git a/docs/troubleshooting/FAQ.mdx b/docs/troubleshooting/FAQ.mdx index eb50ddb23f8c..dd96a721bcc0 100644 --- a/docs/troubleshooting/FAQ.mdx +++ b/docs/troubleshooting/FAQ.mdx @@ -4,6 +4,9 @@ title: FAQs slug: /troubleshooting/ --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## I am using a rule from ESLint core, and it doesn't work correctly with TypeScript code This happens because TypeScript adds new features that ESLint doesn't know about. @@ -114,7 +117,7 @@ Update to the latest version to see a more informative version of this error mes First make sure you've read the docs and understand ESLint configuration files: -- [Read our getting started guide](./getting-started/Quickstart) to ensure your config is properly setup to start configuring our rules. +- [Read our getting started guide](../getting-started/Quickstart.mdx) to ensure your config is properly setup to start configuring our rules. - [Checkout ESLint's documentation on configuring rules](https://eslint.org/docs/latest/use/configure/rules) to ensure you understand how to configure rules. Our [rule docs](/rules) detail the options each rule supports under the "Options" heading. diff --git a/docs/troubleshooting/Formatting.mdx b/docs/troubleshooting/Formatting.mdx index 0b7c15e0c631..ac94a82195b2 100644 --- a/docs/troubleshooting/Formatting.mdx +++ b/docs/troubleshooting/Formatting.mdx @@ -3,6 +3,9 @@ id: formatting title: What About Formatting? --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + We recommend against using ESLint for formatting. We recommend using [Prettier](https://prettier.io), [dprint](https://dprint.dev), or an equivalent instead. diff --git a/docs/troubleshooting/Performance.mdx b/docs/troubleshooting/Performance.mdx index 490b6c0ce650..71a63da234b2 100644 --- a/docs/troubleshooting/Performance.mdx +++ b/docs/troubleshooting/Performance.mdx @@ -3,6 +3,9 @@ id: performance-troubleshooting title: Performance Troubleshooting --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + As mentioned in the [type-aware linting doc](../getting-started/Typed_Linting.mdx), if you're using type-aware linting, your lint times should be roughly the same as your build times. If you're experiencing times much slower than that, then there are a few common culprits. diff --git a/packages/eslint-plugin/docs/rules/README.md b/packages/eslint-plugin/docs/rules/README.md index 7b4d4dde58ed..32c1cefc16e0 100644 --- a/packages/eslint-plugin/docs/rules/README.md +++ b/packages/eslint-plugin/docs/rules/README.md @@ -9,7 +9,7 @@ slug: / `@typescript-eslint/eslint-plugin` includes over 100 rules that detect best practice violations, bugs, and/or stylistic issues specifically for TypeScript code. All of our rules are listed below. :::tip -Instead of enabling rules one by one, we recommend using one of [our pre-defined configs](/linting/configs) to enable a large set of recommended rules. +Instead of enabling rules one by one, we recommend using one of [our pre-defined configs](/users/configs) to enable a large set of recommended rules. ::: ## Rules @@ -24,17 +24,17 @@ import RulesTable from "@site/src/components/RulesTable"; ### Config Group (⚙️) -"Config Group" refers to the [pre-defined config](/linting/configs) that includes the rule. Extending from a configuration preset allow for enabling a large set of recommended rules all at once. +"Config Group" refers to the [pre-defined config](/users/configs) that includes the rule. Extending from a configuration preset allow for enabling a large set of recommended rules all at once. ### Metadata - `🔧 fixable` refers to whether the rule contains an [ESLint `--fix` auto-fixer](https://eslint.org/docs/latest/use/command-line-interface#--fix). - `💡 has suggestions` refers to whether the rule contains an ESLint suggestion fixer. - Sometimes, it is not safe to automatically fix the code with an auto-fixer. But in these cases, we often have a good guess of what the correct fix should be, and we can provide it as a suggestion to the developer. -- `💭 requires type information` refers to whether the rule requires [typed linting](/linting/typed-linting). +- `💭 requires type information` refers to whether the rule requires [typed linting](/getting-started/typed-linting). - `🧱 extension rule` means that the rule is an extension of an [core ESLint rule](https://eslint.org/docs/latest/rules) (see [Extension Rules](#extension-rules)). - `📐 formatting rule` means that the rule has to do with formatting. - - We [strongly recommend against using ESLint for formatting](/linting/troubleshooting/formatting). + - We [strongly recommend against using ESLint for formatting](/troubleshooting/formatting). - Soon, formatting rules will be moved to the [ESLint stylistic plugin](https://eslint.style). - `💀 deprecated rule` means that the rule should no longer be used and will be removed from the plugin in a future version. diff --git a/packages/eslint-plugin/docs/rules/consistent-type-imports.md b/packages/eslint-plugin/docs/rules/consistent-type-imports.md index 496172f342e3..97e6ba147c26 100644 --- a/packages/eslint-plugin/docs/rules/consistent-type-imports.md +++ b/packages/eslint-plugin/docs/rules/consistent-type-imports.md @@ -92,7 +92,7 @@ const x: import('Bar') = 1; The `emitDecoratorMetadata` compiler option changes the code the TypeScript emits. In short - it causes TypeScript to create references to value imports when they are used in a type-only location. If you are using `emitDecoratorMetadata` then our tooling will require additional information in order for the rule to work correctly. -If you are using [type-aware linting](https://typescript-eslint.io/linting/typed-linting), then you just need to ensure that the `tsconfig.json` you've configured for `parserOptions.project` has `emitDecoratorMetadata` turned on. Otherwise you can explicitly tell our tooling to analyze your code as if the compiler option was turned on [by setting `parserOptions.emitDecoratorMetadata` to `true`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/parser/README.md#parseroptionsemitdecoratormetadata). +If you are using [type-aware linting](/getting-started/typed-linting), then you just need to ensure that the `tsconfig.json` you've configured for `parserOptions.project` has `emitDecoratorMetadata` turned on. Otherwise you can explicitly tell our tooling to analyze your code as if the compiler option was turned on [by setting `parserOptions.emitDecoratorMetadata` to `true`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/parser/README.md#parseroptionsemitdecoratormetadata). ## When Not To Use It diff --git a/packages/eslint-plugin/docs/rules/no-extra-semi.md b/packages/eslint-plugin/docs/rules/no-extra-semi.md index 2768bae0df25..b20f22d949d2 100644 --- a/packages/eslint-plugin/docs/rules/no-extra-semi.md +++ b/packages/eslint-plugin/docs/rules/no-extra-semi.md @@ -9,4 +9,4 @@ description: 'Disallow unnecessary semicolons.' This rule extends the base [`eslint/no-extra-semi`](https://eslint.org/docs/rules/no-extra-semi) rule. It adds support for class properties. -Note that this rule is classified as a "Suggestion" rule instead of a "Layout & Formatting" rule because [adding extra semi-colons actually changes the AST of the program](https://typescript-eslint.io/play/#ts=5.1.6&showAST=es&fileType=.ts&code=MYewdgzgLgBAHjAvDAjAbg0A&eslintrc=N4KABGBEBOCuA2BTAzpAXGUEKQHYHsBaRADwBdoBDQ5RAWwEt0p8AzVyAGnG0gAEyATwAOKAMbQGwssWTwGuMgHoCxclRr0mGSImjR80SDwC%2BIE0A&tsconfig=&tokens=false). With that said, modern TypeScript formatters will remove extra semi-colons automatically during the formatting process. Thus, if you [use a formatter](/linting/troubleshooting/formatting), then enabling this rule is probably unnecessary. +Note that this rule is classified as a "Suggestion" rule instead of a "Layout & Formatting" rule because [adding extra semi-colons actually changes the AST of the program](https://typescript-eslint.io/play/#ts=5.1.6&showAST=es&fileType=.ts&code=MYewdgzgLgBAHjAvDAjAbg0A&eslintrc=N4KABGBEBOCuA2BTAzpAXGUEKQHYHsBaRADwBdoBDQ5RAWwEt0p8AzVyAGnG0gAEyATwAOKAMbQGwssWTwGuMgHoCxclRr0mGSImjR80SDwC%2BIE0A&tsconfig=&tokens=false). With that said, modern TypeScript formatters will remove extra semi-colons automatically during the formatting process. Thus, if you [use a formatter](/troubleshooting/formatting), then enabling this rule is probably unnecessary. diff --git a/packages/eslint-plugin/docs/rules/no-type-alias.md b/packages/eslint-plugin/docs/rules/no-type-alias.md index e34b23548bb9..32caada41dc6 100644 --- a/packages/eslint-plugin/docs/rules/no-type-alias.md +++ b/packages/eslint-plugin/docs/rules/no-type-alias.md @@ -16,7 +16,7 @@ TypeScript type aliases are a commonly necessary language feature; banning it al :::note If you want to ban certain classifications of type aliases, consider using [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax). -See [Troubleshooting & FAQs](/linting/troubleshooting#how-can-i-ban-specific-language-feature). +See [Troubleshooting & FAQs](/troubleshooting#how-can-i-ban-specific-language-feature). ::: diff --git a/packages/eslint-plugin/src/configs/all.ts b/packages/eslint-plugin/src/configs/all.ts index b1890165c7ad..4c30f33ed9e5 100644 --- a/packages/eslint-plugin/src/configs/all.ts +++ b/packages/eslint-plugin/src/configs/all.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/eslint-plugin/src/configs/disable-type-checked.ts b/packages/eslint-plugin/src/configs/disable-type-checked.ts index 09a5c07fd3e7..48cf79d56e22 100644 --- a/packages/eslint-plugin/src/configs/disable-type-checked.ts +++ b/packages/eslint-plugin/src/configs/disable-type-checked.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/eslint-plugin/src/configs/recommended-type-checked.ts b/packages/eslint-plugin/src/configs/recommended-type-checked.ts index 6c0a8aff826e..38d36c132851 100644 --- a/packages/eslint-plugin/src/configs/recommended-type-checked.ts +++ b/packages/eslint-plugin/src/configs/recommended-type-checked.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/eslint-plugin/src/configs/recommended.ts b/packages/eslint-plugin/src/configs/recommended.ts index a4c94992c159..80a607a3288f 100644 --- a/packages/eslint-plugin/src/configs/recommended.ts +++ b/packages/eslint-plugin/src/configs/recommended.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/eslint-plugin/src/configs/strict-type-checked.ts b/packages/eslint-plugin/src/configs/strict-type-checked.ts index 5666c64035da..836a0ec76e7c 100644 --- a/packages/eslint-plugin/src/configs/strict-type-checked.ts +++ b/packages/eslint-plugin/src/configs/strict-type-checked.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/eslint-plugin/src/configs/strict.ts b/packages/eslint-plugin/src/configs/strict.ts index 75952e10634b..e49b8cbcadc1 100644 --- a/packages/eslint-plugin/src/configs/strict.ts +++ b/packages/eslint-plugin/src/configs/strict.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/eslint-plugin/src/configs/stylistic-type-checked.ts b/packages/eslint-plugin/src/configs/stylistic-type-checked.ts index 73c1404c3f45..0bb075e5c8f2 100644 --- a/packages/eslint-plugin/src/configs/stylistic-type-checked.ts +++ b/packages/eslint-plugin/src/configs/stylistic-type-checked.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/eslint-plugin/src/configs/stylistic.ts b/packages/eslint-plugin/src/configs/stylistic.ts index 66c31eaa0eb0..74f2586dd78b 100644 --- a/packages/eslint-plugin/src/configs/stylistic.ts +++ b/packages/eslint-plugin/src/configs/stylistic.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/repo-tools/src/generate-configs.mts b/packages/repo-tools/src/generate-configs.mts index acf7819a461a..b32f0b7d5f1c 100644 --- a/packages/repo-tools/src/generate-configs.mts +++ b/packages/repo-tools/src/generate-configs.mts @@ -29,7 +29,7 @@ const chalk = { const AUTO_GENERATED_COMMENT_LINES = [ '// THIS CODE WAS AUTOMATICALLY GENERATED', '// DO NOT EDIT THIS CODE BY HAND', - '// SEE https://typescript-eslint.io/linting/configs', + '// SEE https://typescript-eslint.io/users/configs', '//', '// For developers working in the typescript-eslint monorepo:', '// You can regenerate it using `yarn generate:configs`', diff --git a/packages/typescript-eslint/src/configs/all.ts b/packages/typescript-eslint/src/configs/all.ts index f891ff9b92f4..ebade354a351 100644 --- a/packages/typescript-eslint/src/configs/all.ts +++ b/packages/typescript-eslint/src/configs/all.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/typescript-eslint/src/configs/disable-type-checked.ts b/packages/typescript-eslint/src/configs/disable-type-checked.ts index da3a0b7256df..17801026e24a 100644 --- a/packages/typescript-eslint/src/configs/disable-type-checked.ts +++ b/packages/typescript-eslint/src/configs/disable-type-checked.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/typescript-eslint/src/configs/recommended-type-checked.ts b/packages/typescript-eslint/src/configs/recommended-type-checked.ts index 7d9ac811e1c7..77feebb92cba 100644 --- a/packages/typescript-eslint/src/configs/recommended-type-checked.ts +++ b/packages/typescript-eslint/src/configs/recommended-type-checked.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/typescript-eslint/src/configs/recommended.ts b/packages/typescript-eslint/src/configs/recommended.ts index ae5103d9fea8..042891ebf9b2 100644 --- a/packages/typescript-eslint/src/configs/recommended.ts +++ b/packages/typescript-eslint/src/configs/recommended.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/typescript-eslint/src/configs/strict-type-checked.ts b/packages/typescript-eslint/src/configs/strict-type-checked.ts index c1c4628d0cdf..91abadd4b563 100644 --- a/packages/typescript-eslint/src/configs/strict-type-checked.ts +++ b/packages/typescript-eslint/src/configs/strict-type-checked.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/typescript-eslint/src/configs/strict.ts b/packages/typescript-eslint/src/configs/strict.ts index e54b7d07322e..c1eb5e29cf3d 100644 --- a/packages/typescript-eslint/src/configs/strict.ts +++ b/packages/typescript-eslint/src/configs/strict.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/typescript-eslint/src/configs/stylistic-type-checked.ts b/packages/typescript-eslint/src/configs/stylistic-type-checked.ts index 3923973100b3..e72f5accc5f9 100644 --- a/packages/typescript-eslint/src/configs/stylistic-type-checked.ts +++ b/packages/typescript-eslint/src/configs/stylistic-type-checked.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/typescript-eslint/src/configs/stylistic.ts b/packages/typescript-eslint/src/configs/stylistic.ts index 4db1a78f9a0a..a8b9a0368c2d 100644 --- a/packages/typescript-eslint/src/configs/stylistic.ts +++ b/packages/typescript-eslint/src/configs/stylistic.ts @@ -1,6 +1,6 @@ // THIS CODE WAS AUTOMATICALLY GENERATED // DO NOT EDIT THIS CODE BY HAND -// SEE https://typescript-eslint.io/linting/configs +// SEE https://typescript-eslint.io/users/configs // // For developers working in the typescript-eslint monorepo: // You can regenerate it using `yarn generate:configs` diff --git a/packages/website/blog/2023-03-13-announcing-typescript-eslint-v6-beta.md b/packages/website/blog/2023-03-13-announcing-typescript-eslint-v6-beta.md index d0b2d1c36b4f..38f9f289d03f 100644 --- a/packages/website/blog/2023-03-13-announcing-typescript-eslint-v6-beta.md +++ b/packages/website/blog/2023-03-13-announcing-typescript-eslint-v6-beta.md @@ -33,11 +33,10 @@ If you feel passionately about any of the choices we've made here -positively or ## Trying Out v6 Please do try out the typescript-eslint v6 beta! -Its documentation site is hosted on a preview deploy link: **[v6--typescript-eslint.netlify.app](https://v6--typescript-eslint.netlify.app)**. ### As A New User -If you don't yet use typescript-eslint, you can go through our [configuration steps on the v6 _Getting Started_ docs](https://v6--typescript-eslint.netlify.app/getting-started). +If you don't yet use typescript-eslint, you can go through our [configuration steps on the v6 _Getting Started_ docs](/getting-started). It'll walk you through setting up typescript-eslint in a project. To use v6 specifically, see the following section for an updated install command. @@ -61,12 +60,12 @@ These are the changes that users of typescript-eslint -generally, any developer ### Reworked Configuration Names -The biggest configuration change in typescript-eslint v6 is that we've reworked the names of our [provided user configuration files](https://v6--typescript-eslint.netlify.app/linting/configs). +The biggest configuration change in typescript-eslint v6 is that we've reworked the names of our [provided user configuration files](/users/configs). typescript-eslint v5 provided three recommended configurations: -- [`recommended`](https://v6--typescript-eslint.netlify.app/linting/configs#recommended): Recommended rules for code correctness that you can drop in without additional configuration. -- [`recommended-requiring-type-checking`](https://v6--typescript-eslint.netlify.app/linting/configs#recommended-requiring-type-checking): Additional recommended rules that require type information. -- [`strict`](https://v6--typescript-eslint.netlify.app/linting/configs#strict): Additional strict rules that can also catch bugs but are more opinionated than recommended rules. +- [`recommended`](/users/configs#recommended): Recommended rules for code correctness that you can drop in without additional configuration. +- [`recommended-requiring-type-checking`](/users/configs#recommended-requiring-type-checking): Additional recommended rules that require type information. +- [`strict`](/users/configs#strict): Additional strict rules that can also catch bugs but are more opinionated than recommended rules. Those configurations worked well for most projects. However, some users correctly noted two flaws in that approach: @@ -121,7 +120,7 @@ module.exports = { }; ``` -See [_Configurations_ on the v6 docs site preview](https://v6--typescript-eslint.netlify.app/linting/configs) for the updated documentation on configurations provided by typescript-eslint. +See [_Configurations_ on the v6 docs site preview](/users/configs) for the updated documentation on configurations provided by typescript-eslint. For more information on these changes, see: @@ -165,8 +164,8 @@ Several rules were changed in significant enough ways to be considered breaking - `@typescript-eslint/no-implicit-any-catch` - `@typescript-eslint/no-parameter-properties` - `@typescript-eslint/sort-type-union-intersection-members` -- [feat(eslint-plugin): [prefer-nullish-coalescing]: add support for assignment expressions](https://github.com/typescript-eslint/typescript-eslint/pull/5234): Enhances the [`@typescript-eslint/prefer-nullish-coalescing`](https://v6--typescript-eslint.netlify.app/prefer-nullish-coalescing) rule to also check `||=` expressions. -- [feat(eslint-plugin): [prefer-optional-chain] use type checking for strict falsiness](https://github.com/typescript-eslint/typescript-eslint/pull/6240): Rewrites the [`@typescript-eslint/prefer-optional-chain`](https://v6--typescript-eslint.netlify.app/prefer-optional-chain) rule to fix numerous false positives, at the cost of making it require type information. +- [feat(eslint-plugin): [prefer-nullish-coalescing]: add support for assignment expressions](https://github.com/typescript-eslint/typescript-eslint/pull/5234): Enhances the [`@typescript-eslint/prefer-nullish-coalescing`](/rules/prefer-nullish-coalescing) rule to also check `||=` expressions. +- [feat(eslint-plugin): [prefer-optional-chain] use type checking for strict falsiness](https://github.com/typescript-eslint/typescript-eslint/pull/6240): Rewrites the [`@typescript-eslint/prefer-optional-chain`](/rules/prefer-optional-chain) rule to fix numerous false positives, at the cost of making it require type information. ### Tooling Breaking Changes @@ -242,7 +241,7 @@ Rules can still retrieve their full backing TypeScript type checker with `servic This can be necessary for TypeScript APIs not wrapped by the parser services. ::: -See [_Custom Rules_ on the v6 docs site preview](https://v6--typescript-eslint.netlify.app/developers/custom-rules) for the updated documentation on creating custom rules with typescript-eslint. +See [_Custom Rules_ on the v6 docs site preview](/developers/custom-rules) for the updated documentation on creating custom rules with typescript-eslint. ### AST Breaking Changes diff --git a/packages/website/blog/2023-07-09-announcing-typescript-eslint-v6.md b/packages/website/blog/2023-07-09-announcing-typescript-eslint-v6.md index f1db265643da..e0352744d189 100644 --- a/packages/website/blog/2023-07-09-announcing-typescript-eslint-v6.md +++ b/packages/website/blog/2023-07-09-announcing-typescript-eslint-v6.md @@ -46,12 +46,12 @@ These are the changes that users of typescript-eslint -generally, any developer ### Reworked Configuration Names -The biggest configuration change in typescript-eslint v6 is that we've reworked the names of our [provided user configuration files](https://typescript-eslint.io/linting/configs). +The biggest configuration change in typescript-eslint v6 is that we've reworked the names of our [provided user configuration files](/users/configs). typescript-eslint v5 provided three recommended configurations: -- [`recommended`](https://typescript-eslint.io/linting/configs#recommended): Recommended rules for code correctness that you can drop in without additional configuration. -- [`recommended-requiring-type-checking`](https://typescript-eslint.io/linting/configs#recommended-requiring-type-checking): Additional recommended rules that require type information. -- [`strict`](https://typescript-eslint.io/linting/configs#strict): Additional strict rules that can also catch bugs but are more opinionated than recommended rules. +- [`recommended`](/users/configs#recommended): Recommended rules for code correctness that you can drop in without additional configuration. +- [`recommended-requiring-type-checking`](/users/configs#recommended-requiring-type-checking): Additional recommended rules that require type information. +- [`strict`](/users/configs#strict): Additional strict rules that can also catch bugs but are more opinionated than recommended rules. Those configurations worked well for most projects. However, some users correctly noted two flaws in that approach: @@ -106,11 +106,11 @@ module.exports = { }; ``` -See [our _Configurations_ linting docs](/linting/configs) for the updated documentation on configurations provided by typescript-eslint. +See [our _Configurations_ linting docs](/users/configs) for the updated documentation on configurations provided by typescript-eslint. For more information on these changes, see: -- [Our documentation on our configurations](https://typescript-eslint.io/linting/configs). +- [Our documentation on our configurations](/users/configs). - [Configs: Have recommended/strict configs include lesser configs, and simplify type checked names](https://github.com/typescript-eslint/typescript-eslint/discussions/6019) for the discussion leading up to these configuration changes. - [feat(eslint-plugin): rework configs: recommended, strict, stylistic; -type-checked](https://github.com/typescript-eslint/typescript-eslint/pull/5251) for the pull request implementing the changes. @@ -485,8 +485,8 @@ Several rules were changed in significant enough ways to be considered breaking - `@typescript-eslint/no-implicit-any-catch`, replaced by the TSConfig option [`useUnknownInCatchVariables`](https://www.typescriptlang.org/tsconfig#useUnknownInCatchVariables) - `@typescript-eslint/no-parameter-properties`, replaced by `@typescript-eslint/parameter-properties` - `@typescript-eslint/sort-type-union-intersection-members`, replaced by `@typescript-eslint/sort-type-constituents` -- [feat(eslint-plugin): [prefer-nullish-coalescing]: add support for assignment expressions](https://github.com/typescript-eslint/typescript-eslint/pull/5234): Enhances the [`@typescript-eslint/prefer-nullish-coalescing`](https://typescript-eslint.io/prefer-nullish-coalescing) rule to also check `||=` expressions. -- [feat(eslint-plugin): [prefer-optional-chain] use type checking for strict falsiness](https://github.com/typescript-eslint/typescript-eslint/pull/6240): Fixes edge case bugs in the [`@typescript-eslint/prefer-optional-chain`](https://typescript-eslint.io/prefer-optional-chain) rule around false positives, at the cost of making it require type information. +- [feat(eslint-plugin): [prefer-nullish-coalescing]: add support for assignment expressions](https://github.com/typescript-eslint/typescript-eslint/pull/5234): Enhances the [`@typescript-eslint/prefer-nullish-coalescing`](/rules/prefer-nullish-coalescing) rule to also check `||=` expressions. +- [feat(eslint-plugin): [prefer-optional-chain] use type checking for strict falsiness](https://github.com/typescript-eslint/typescript-eslint/pull/6240): Fixes edge case bugs in the [`@typescript-eslint/prefer-optional-chain`](/rules/prefer-optional-chain) rule around false positives, at the cost of making it require type information. - ✨ [feat(eslint-plugin): [restrict-plus-operands] change checkCompoundAssignments to skipCompoundAssignments](https://github.com/typescript-eslint/typescript-eslint/pull/7027): inverses the logical value of the option and renames it - ✨ [feat(eslint-plugin): [prefer-optional-chain] handle cases where the first operands are unrelated to the rest of the chain and add type info](https://github.com/typescript-eslint/typescript-eslint/pull/6397): uses type information to make the rule more intelligent about when to flag violations @@ -561,7 +561,7 @@ Rules can still retrieve their full backing TypeScript type checker with `servic This can be necessary for TypeScript APIs not wrapped by the parser services. ::: -See [_Custom Rules_](https://typescript-eslint.io/developers/custom-rules) for the updated documentation on creating custom rules with typescript-eslint. +See [_Custom Rules_](/developers/custom-rules) for the updated documentation on creating custom rules with typescript-eslint. ### AST Breaking Changes diff --git a/packages/website/blog/2023-09-18-parser-options-project-true.md b/packages/website/blog/2023-09-18-parser-options-project-true.md index a28bb69c30ec..c767972508ae 100644 --- a/packages/website/blog/2023-09-18-parser-options-project-true.md +++ b/packages/website/blog/2023-09-18-parser-options-project-true.md @@ -10,7 +10,7 @@ tags: [parser, parser options, project, tsconfig] title: Relative TSConfig Projects with `parserOptions.project = true` --- -["Typed linting"](/linting/typed-linting), or enabling ESLint rules to tap into the power of the TypeScript type checker, is one of the best parts of typescript-eslint. +["Typed linting"](/getting-started/typed-linting), or enabling ESLint rules to tap into the power of the TypeScript type checker, is one of the best parts of typescript-eslint. But enabling the type checker in repositories with multiple `tsconfig.json` files can be annoying to set up. Even worse, specifying the wrong include paths could result in incorrect rule reports and/or unexpectedly slow lint times. @@ -51,7 +51,7 @@ Explicitly indicating which TSConfig files are used for typed linting can be use Developers like being given explicit control over their tooling. However, we've seen a few issues arise from this approach: -- Particularly large repos can end up with so many TSConfig globs, they become confusing to developers or even cause [performance issues from overly permissive globs](/linting/troubleshooting/performance-troubleshooting#wide-includes-in-your-eslint-options) +- Particularly large repos can end up with so many TSConfig globs, they become confusing to developers or even cause [performance issues from overly permissive globs](/troubleshooting/performance-troubleshooting#wide-includes-in-your-eslint-options) - Needing to change a template ESLint config every time it's used for a different repository structure is a pain - Using a TSConfig that's different from what your editor uses can result in different lint reports between the editor and the command-line @@ -135,7 +135,7 @@ Manual Program creation logic comes with a few issues: - For example, [typescript-eslint does not yet support Project References](https://github.com/typescript-eslint/typescript-eslint/issues/2094). - The TypeScript compiler options used in the user's editor might differ from the compiler options in the TSConfigs they specified on disk. - Files not included in created Programs can't be linted with type information, even though editors still typically surface type information when editing those files. - - Most commonly, `.eslintrc.(c)js` files can be tricky to lint, resulting in the dreaded [_TSConfig does not include this file_ error](/linting/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). + - Most commonly, `.eslintrc.(c)js` files can be tricky to lint, resulting in the dreaded [_TSConfig does not include this file_ error](/troubleshooting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). We're working on an option to instead call the same TypeScript "Project Service" APIs that editors such as VS Code use to create Programs for us instead. Project Services will automatically detect the TSConfig for each file (like `project: true`), and will also allow type information to be computed for JavaScript files without the `allowJs` compiler option (unlike `project: true`). diff --git a/packages/website/blog/2023-12-25-deprecating-formatting-rules.md b/packages/website/blog/2023-12-25-deprecating-formatting-rules.md index 439a8b4be14d..9bb344ee696f 100644 --- a/packages/website/blog/2023-12-25-deprecating-formatting-rules.md +++ b/packages/website/blog/2023-12-25-deprecating-formatting-rules.md @@ -21,8 +21,8 @@ We'll keep these deprecated rules available until our next major version. ## Context: Formatting Rules The ESLint blog post thoroughly explains the history and tradeoffs of formatting rules. -See also [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies/#what-are-the-changes) and our _[What About Formatting?](/linting/troubleshooting/formatting)_ docs. -The performance downsides of formatting rules are heightened when [linting with type information](/linting/typed-linting). +See also [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies/#what-are-the-changes) and our _[What About Formatting?](/troubleshooting/formatting)_ docs. +The performance downsides of formatting rules are heightened when [linting with type information](/getting-started/typed-linting). ## Timelines diff --git a/packages/website/docusaurusConfig.ts b/packages/website/docusaurusConfig.ts index 2ee976cf08cc..1598f96ffefa 100644 --- a/packages/website/docusaurusConfig.ts +++ b/packages/website/docusaurusConfig.ts @@ -1,4 +1,5 @@ import type { MDXPlugin } from '@docusaurus/mdx-loader'; +import type { Options as PluginRedirectOptions } from '@docusaurus/plugin-client-redirects'; import type { Options as PluginContentDocsOptions } from '@docusaurus/plugin-content-docs'; import type { Options as PluginPwaOptions } from '@docusaurus/plugin-pwa'; import type { Options as PresetClassicOptions } from '@docusaurus/preset-classic'; @@ -254,6 +255,39 @@ const pluginPwaOptions: PluginPwaOptions = { ], }; +const redirects: PluginRedirectOptions = { + redirects: [ + { + from: '/linting/configs', + to: '/users/configs', + }, + { + from: '/linting/troubleshooting', + to: '/troubleshooting', + }, + { + from: '/linting/troubleshooting/formatting', + to: '/troubleshooting/formatting', + }, + { + from: '/linting/troubleshooting/performance-troubleshooting', + to: '/troubleshooting/performance-troubleshooting', + }, + { + from: '/linting/troubleshooting/tslint', + to: '/troubleshooting/tslint', + }, + { + from: '/linting/typed-linting', + to: '/getting-started/typed-linting', + }, + { + from: '/linting/typed-linting/monorepos', + to: '/getting-started/typed-linting/monorepos', + }, + ], +}; + const config: Config = { title: 'typescript-eslint', tagline: @@ -274,6 +308,7 @@ const config: Config = { require.resolve('./webpack.plugin'), ['@docusaurus/plugin-content-docs', pluginContentDocsOptions], ['@docusaurus/plugin-pwa', pluginPwaOptions], + ['@docusaurus/plugin-client-redirects', redirects], ], themeConfig, // Misleading API name, but these are just tags diff --git a/packages/website/package.json b/packages/website/package.json index 6efa09738ce4..d29a8499d1ae 100644 --- a/packages/website/package.json +++ b/packages/website/package.json @@ -18,6 +18,7 @@ "dependencies": { "@babel/runtime": "^7.22.6", "@docusaurus/core": "~2.4.1", + "@docusaurus/plugin-client-redirects": "~2.4.3", "@docusaurus/plugin-pwa": "~2.4.1", "@docusaurus/preset-classic": "~2.4.1", "@docusaurus/remark-plugin-npm2yarn": "~2.4.1", diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts b/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts index 170a8f33a5d8..ad7949c4c6e4 100644 --- a/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts +++ b/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts @@ -34,7 +34,7 @@ export function insertWhenNotToUseIt(page: RuleDocsPage): void { { type: 'link', title: null, - url: `/linting/typed-linting`, + url: `/getting-started/typed-linting`, children: [ { type: 'text', @@ -49,7 +49,7 @@ export function insertWhenNotToUseIt(page: RuleDocsPage): void { { type: 'link', title: null, - url: `/linting/troubleshooting/performance-troubleshooting`, + url: `/troubleshooting/performance-troubleshooting`, children: [ { type: 'text', diff --git a/packages/website/src/theme/MDXComponents/RuleAttributes.tsx b/packages/website/src/theme/MDXComponents/RuleAttributes.tsx index 365dd15b1e8d..8340657d7742 100644 --- a/packages/website/src/theme/MDXComponents/RuleAttributes.tsx +++ b/packages/website/src/theme/MDXComponents/RuleAttributes.tsx @@ -43,7 +43,7 @@ export function RuleAttributes({ name }: { name: string }): React.ReactNode { children: ( <> Extending{' '} - + "plugin:@typescript-eslint/{recommendation}" @@ -94,7 +94,7 @@ export function RuleAttributes({ name }: { name: string }): React.ReactNode { children: ( <> This rule requires{' '} - + type information {' '} to run. diff --git a/yarn.lock b/yarn.lock index 939e4ba03842..43e2d537027f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2503,6 +2503,26 @@ __metadata: languageName: node linkType: hard +"@docusaurus/plugin-client-redirects@npm:~2.4.3": + version: 2.4.3 + resolution: "@docusaurus/plugin-client-redirects@npm:2.4.3" + dependencies: + "@docusaurus/core": 2.4.3 + "@docusaurus/logger": 2.4.3 + "@docusaurus/utils": 2.4.3 + "@docusaurus/utils-common": 2.4.3 + "@docusaurus/utils-validation": 2.4.3 + eta: ^2.0.0 + fs-extra: ^10.1.0 + lodash: ^4.17.21 + tslib: ^2.4.0 + peerDependencies: + react: ^16.8.4 || ^17.0.0 + react-dom: ^16.8.4 || ^17.0.0 + checksum: f039f89ad2658524819543ff4a370e409053bfd3b4851be82c3cceb6fcd39e954a1ca3bfd13e99fbd1f7fbb9cd69ed28545a852c8dbca2e8300eec23586767a4 + languageName: node + linkType: hard + "@docusaurus/plugin-content-blog@npm:2.4.3": version: 2.4.3 resolution: "@docusaurus/plugin-content-blog@npm:2.4.3" @@ -19260,6 +19280,7 @@ __metadata: "@babel/runtime": ^7.22.6 "@docusaurus/core": ~2.4.1 "@docusaurus/module-type-aliases": ~2.4.1 + "@docusaurus/plugin-client-redirects": ~2.4.3 "@docusaurus/plugin-pwa": ~2.4.1 "@docusaurus/preset-classic": ~2.4.1 "@docusaurus/remark-plugin-npm2yarn": ~2.4.1 From b4784bcdb3ba75014185a635422f487611b3e45e Mon Sep 17 00:00:00 2001 From: Brad Zacher Date: Tue, 20 Feb 2024 11:51:05 +1030 Subject: [PATCH 3/3] review --- docs/getting-started/Quickstart.mdx | 3 +- docs/packages/TypeScript_ESLint.mdx | 73 ++++++++++++--- .../flat-config-types/eslint.config.js | 60 +++++++------ .../flat-config-types.test.ts.snap | 89 ++++++++++++------- 4 files changed, 152 insertions(+), 73 deletions(-) diff --git a/docs/getting-started/Quickstart.mdx b/docs/getting-started/Quickstart.mdx index 2a5a2fba75cc..2d38219ef24c 100644 --- a/docs/getting-started/Quickstart.mdx +++ b/docs/getting-started/Quickstart.mdx @@ -44,7 +44,7 @@ export default tseslint.config( ); ``` -This code will enable our recommended configuration for linting +This code will enable our [recommended configuration](../users/Shared_Configurations.mdx) for linting. ### Step 3: Running ESLint @@ -88,7 +88,6 @@ See [ESLint's Configuration Files docs](https://eslint.org/docs/user-guide/confi We provide a plethora of powerful rules that utilize the power of TypeScript's type information. -[Visit the next] [Visit the next page for a setup guide](./Typed_Linting.mdx 'Visit the next page for a typed rules setup guide'). If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](../troubleshooting/FAQ.mdx). diff --git a/docs/packages/TypeScript_ESLint.mdx b/docs/packages/TypeScript_ESLint.mdx index 8ea449568e15..c5f1d2665245 100644 --- a/docs/packages/TypeScript_ESLint.mdx +++ b/docs/packages/TypeScript_ESLint.mdx @@ -55,17 +55,63 @@ export default tseslint.config( This config file exports a flat config that enables both the [core eslint recommended config](https://www.npmjs.com/package/@eslint/js) and [our recommended config](../users/Shared_Configurations.mdx#recommended). -For more information on the `tseslint.config` function [see below](#config). +For more information on the `tseslint.config` function [see `config(...)` below](#config). ### Advanced usage -You can also declare our plugin and parser in your config via this package. For example this config would enable our plugin, our parser, and type-aware linting with a few of our popular type-aware rules: +#### Manually configuring our plugin and parser + +You can declare our plugin and parser in your config via this package, for example: ```js title="eslint.config.js" // @ts-check import eslint from '@eslint/js'; -import importPlugin from 'eslint-plugin-import'; +import jestPlugin from 'eslint-plugin-jest'; +import tseslint from 'typescript-eslint'; + +export default tseslint.config({ + plugins: { + // highlight-next-line + '@typescript-eslint': tseslint.plugin, + }, + languageOptions: { + // highlight-next-line + parser: tseslint.parser, + parserOptions: { + project: true, + }, + }, + rules: { + '@typescript-eslint/no-unsafe-argument': 'error', + '@typescript-eslint/no-unsafe-assignment': 'error', + '@typescript-eslint/no-unsafe-call': 'error', + '@typescript-eslint/no-unsafe-member-access': 'error', + '@typescript-eslint/no-unsafe-return': 'error', + }, +}); +``` + +:::warning +We **_strongly_** recommend declaring our plugin with the namespace `@typescript-eslint` as shown above. If you use our shared configs this is the namespace that they use. This has been the standard namespace for our plugin for many years and is what users are most familiar with. + +You may choose a different namespace - but note that currently [flat configs allow the same plugin to be registered, configured, and have duplicate reports under multiple namespaces](https://github.com/eslint/eslint/discussions/17766). +::: + +#### Usage with other plugins + +Below is a more complex example of how you might use our tooling with flat configs. This config: + +- Ignores `build`/`dist` folders from being linted +- Enables our plugin, our parser, and type-aware linting with a few of our popular type-aware rules +- Disables type-aware linting on JS files +- Enables the recommended `eslint-plugin-jest` rules on test files only + +```js title="eslint.config.js" +// @ts-check + +import eslint from '@eslint/js'; +import jestPlugin from 'eslint-plugin-jest'; import tseslint from 'typescript-eslint'; export default tseslint.config( @@ -98,18 +144,19 @@ export default tseslint.config( files: ['**/*.js'], ...tseslint.configs.disableTypeChecked, }, + { + // enable jest rules on test files + files: ['test/**'], + ...jestPlugin.configs['flat/recommended'], + }, ); ``` -:::warning -We **_strongly_** recommend declaring our plugin with the namespace `@typescript-eslint` as shown above. If you use our shared configs this is the namespace that they use. This has been the standard namespace for our plugin for many years and is what users are most familiar with. - -You may choose a different namespace - but note that currently [flat configs allow the same plugin to be registered, configured, and have duplicate reports under multiple namespaces](https://github.com/eslint/eslint/discussions/17766). -::: - ## `config(...)` -The `config` function is a [variadic](https://en.wikipedia.org/wiki/Variadic_function) [identity function](https://en.wikipedia.org/wiki/Identity_function) which is a fancy way of saying that it's a function that takes `1..n` inputs and returns the inputs unchanged. It can be used to quickly and easily provide types for your flat config file. By using this function you will get autocomplete and documentation for all config properties in addition to TypeScript errors should you provide invalid values. +The `config` function is a [variadic](https://en.wikipedia.org/wiki/Variadic_function) [identity function](https://en.wikipedia.org/wiki/Identity_function) which is a fancy way of saying that it's a function with a spread argument that accepts any number flat config objects and returns the objects unchanged. It exists as a way to quickly and easily provide types for your flat config file without the need for JSDoc type comments. + +By using this function you will get autocomplete and documentation for all config properties in addition to TypeScript errors, should you provide invalid values. @@ -154,7 +201,7 @@ export default [ :::note -We _**strongly**_ recommend using this utility to improve the config authoring experience — however it is entirely optional and choosing not to use it will not impact your ability to use our tooling; you'll just need to manually adjust any examples as appropriate. +We _**strongly**_ recommend using this utility to improve the config authoring experience — however it is entirely optional. By choosing not to use it you lose editor autocomplete and type checking for config files but otherwise it _will not_ impact your ability to use our tooling. ::: ### Flat config `extends` @@ -194,7 +241,9 @@ export default [ ]; ``` -We found that this is a pretty common operation when writing ESLint configs which is why we provided this convenience property. For example in codebases with type-aware linting a config object like this is a very common way to disable TS-specific linting setups on JS files: +We found that this is a pretty common operation when writing ESLint configs which is why we provided this convenience property. + +For example in codebases with type-aware linting a config object like this is a very common way to disable TS-specific linting setups on JS files: ```js export default tseslint.config([ diff --git a/packages/integration-tests/fixtures/flat-config-types/eslint.config.js b/packages/integration-tests/fixtures/flat-config-types/eslint.config.js index 93701448726a..a7096065b106 100644 --- a/packages/integration-tests/fixtures/flat-config-types/eslint.config.js +++ b/packages/integration-tests/fixtures/flat-config-types/eslint.config.js @@ -18,6 +18,10 @@ const compat = new FlatCompat({ // this config is run through eslint as part of the integration test // so it needs to be a correct config export default tseslint.config( + { + // config with just ignores is the replacement for `.eslintignore` + ignores: ['**/build/**', '**/dist/**', 'src/some/file/to/ignore.ts'], + }, { plugins: { ['@typescript-eslint']: tseslint.plugin, @@ -30,28 +34,34 @@ export default tseslint.config( stylisticPlugin.configs['recommended-flat'], ); -// these are just tests for the types and are not seen by eslint so they can be whatever -tseslint.config({ - plugins: { - ['@stylistic']: stylisticPlugin, - ['@typescript-eslint']: tseslint.plugin, - ['deprecation']: deprecationPlugin, - ['jest']: jestPlugin, - }, -}); -tseslint.config( - eslint.configs.recommended, - ...tseslint.configs.recommended, - stylisticPlugin.configs['recommended-flat'], -); -tseslint.config( - // @ts-expect-error - compat.config(deprecationPlugin.configs.recommended), - ...compat.config(jestPlugin.configs.recommended), -); -tseslint.config( - // @ts-expect-error - deprecationPlugin.configs.recommended, - // this should error but doesn't because there are no types exported from the jest plugin - jestPlugin.configs.recommended, -); +// wrapped in a function so they aren't executed at lint time +function _otherCases() { + // these are just tests for the types and are not seen by eslint so they can be whatever + tseslint.config({ + plugins: { + ['@stylistic']: stylisticPlugin, + ['@typescript-eslint']: tseslint.plugin, + ['deprecation']: deprecationPlugin, + ['jest']: jestPlugin, + }, + }); + tseslint.config( + eslint.configs.recommended, + ...tseslint.configs.recommended, + stylisticPlugin.configs['recommended-flat'], + jestPlugin.configs['flat/recommended'], + ); + tseslint.config( + // @ts-expect-error + compat.config(deprecationPlugin.configs.recommended), + ...compat.config(jestPlugin.configs.recommended), + ); + tseslint.config( + // @ts-expect-error + deprecationPlugin.configs.recommended, + // this should error but doesn't because there are no types exported from the jest plugin + jestPlugin.configs.recommended, + // this should error but doesn't because there are no types exported from the jest plugin + ...jestPlugin.configs['flat/recommended'], + ); +} diff --git a/packages/integration-tests/tests/__snapshots__/flat-config-types.test.ts.snap b/packages/integration-tests/tests/__snapshots__/flat-config-types.test.ts.snap index 4280148fc361..a4ff003ab83b 100644 --- a/packages/integration-tests/tests/__snapshots__/flat-config-types.test.ts.snap +++ b/packages/integration-tests/tests/__snapshots__/flat-config-types.test.ts.snap @@ -3,17 +3,28 @@ exports[`flat-config-types eslint should work successfully 1`] = ` [ { - "errorCount": 2, + "errorCount": 3, "fatalErrorCount": 0, "filePath": "/eslint.config.js", "fixableErrorCount": 0, "fixableWarningCount": 0, "messages": [ { - "column": 3, - "endColumn": 22, - "endLine": 48, - "line": 48, + "column": 10, + "endColumn": 21, + "endLine": 38, + "line": 38, + "message": "'_otherCases' is defined but never used.", + "messageId": "unusedVar", + "nodeType": "Identifier", + "ruleId": "@typescript-eslint/no-unused-vars", + "severity": 2, + }, + { + "column": 5, + "endColumn": 24, + "endLine": 55, + "line": 55, "message": "Include a description after the "@ts-expect-error" directive to explain why the @ts-expect-error is necessary. The description must be 3 characters or longer.", "messageId": "tsDirectiveCommentRequiresDescription", "nodeType": "Line", @@ -21,10 +32,10 @@ exports[`flat-config-types eslint should work successfully 1`] = ` "severity": 2, }, { - "column": 3, - "endColumn": 22, - "endLine": 53, - "line": 53, + "column": 5, + "endColumn": 24, + "endLine": 60, + "line": 60, "message": "Include a description after the "@ts-expect-error" directive to explain why the @ts-expect-error is necessary. The description must be 3 characters or longer.", "messageId": "tsDirectiveCommentRequiresDescription", "nodeType": "Line", @@ -52,6 +63,10 @@ const compat = new FlatCompat({ // this config is run through eslint as part of the integration test // so it needs to be a correct config export default tseslint.config( + { + // config with just ignores is the replacement for \`.eslintignore\` + ignores: ['**/build/**', '**/dist/**', 'src/some/file/to/ignore.ts'], + }, { plugins: { ['@typescript-eslint']: tseslint.plugin, @@ -64,31 +79,37 @@ export default tseslint.config( stylisticPlugin.configs['recommended-flat'], ) -// these are just tests for the types and are not seen by eslint so they can be whatever -tseslint.config({ - plugins: { - ['@stylistic']: stylisticPlugin, - ['@typescript-eslint']: tseslint.plugin, - ['deprecation']: deprecationPlugin, - ['jest']: jestPlugin, - }, -}) -tseslint.config( - eslint.configs.recommended, - ...tseslint.configs.recommended, - stylisticPlugin.configs['recommended-flat'], -) -tseslint.config( - // @ts-expect-error - compat.config(deprecationPlugin.configs.recommended), - ...compat.config(jestPlugin.configs.recommended), -) -tseslint.config( - // @ts-expect-error - deprecationPlugin.configs.recommended, - // this should error but doesn't because there are no types exported from the jest plugin - jestPlugin.configs.recommended, -) +// wrapped in a function so they aren't executed at lint time +function _otherCases() { + // these are just tests for the types and are not seen by eslint so they can be whatever + tseslint.config({ + plugins: { + ['@stylistic']: stylisticPlugin, + ['@typescript-eslint']: tseslint.plugin, + ['deprecation']: deprecationPlugin, + ['jest']: jestPlugin, + }, + }) + tseslint.config( + eslint.configs.recommended, + ...tseslint.configs.recommended, + stylisticPlugin.configs['recommended-flat'], + jestPlugin.configs['flat/recommended'], + ) + tseslint.config( + // @ts-expect-error + compat.config(deprecationPlugin.configs.recommended), + ...compat.config(jestPlugin.configs.recommended), + ) + tseslint.config( + // @ts-expect-error + deprecationPlugin.configs.recommended, + // this should error but doesn't because there are no types exported from the jest plugin + jestPlugin.configs.recommended, + // this should error but doesn't because there are no types exported from the jest plugin + ...jestPlugin.configs['flat/recommended'], + ) +} ", "suppressedMessages": [], "usedDeprecatedRules": [