diff --git a/docs/linting/CONFIGURATIONS.md b/docs/linting/CONFIGURATIONS.md deleted file mode 100644 index de05a216ff87..000000000000 --- a/docs/linting/CONFIGURATIONS.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -id: configs -title: Configurations ---- - -[ESLint shareable configurations](https://eslint.org/docs/latest/developer-guide/shareable-configs) exist to provide a comprehensive base config for you, with the intention that you add the config and it gives you an opinionated setup. - -## Built-In Configurations - -`@typescript-eslint/eslint-plugin` includes built-in configurations you can extend from to pull in the recommended starting rules. - -With the exception of `strict`, all configurations are considered "stable". -Rule additions and removals are treated as breaking changes and will only be done in major version bumps. - -:::note -We recommend most packages extend from [`recommended-requiring-type-checking`](#recommended-requiring-type-checking) (which requires [typed linting](./TYPED_LINTING.md)). -::: - -### `eslint-recommended` - -This ruleset is meant to be used after extending `eslint:recommended`. -It disables core ESLint rules that are already checked by the TypeScript compiler. -Additionally, it enables rules that promote using the more modern constructs TypeScript allows for. - -```jsonc -{ - "extends": [ - "eslint:recommended", - "plugin:@typescript-eslint/eslint-recommended" - ] -} -``` - -This config is automatically included if you use any of the other configurations mentioned on this page. - -### `recommended` - -Recommended rules for code correctness that you can drop in without additional configuration. -These rules are those whose reports are almost always for a bad practice and/or likely bug. -`recommended` also disables rules known to conflict with this repository, or cause issues in TypeScript codebases. - -```json -{ - "extends": ["plugin:@typescript-eslint/recommended"] -} -``` - -:::tip -We strongly recommend all TypeScript projects extend from this configuration. -::: - -### `recommended-requiring-type-checking` - -Additional recommended rules that require type information. -Rules in this configuration are similarly useful to those in `recommended`. - -```json -{ - "extends": [ - "plugin:@typescript-eslint/recommended", - "plugin:@typescript-eslint/recommended-requiring-type-checking" - ] -} -``` - -:::tip -We recommend all TypeScript projects extend from this configuration, with the caveat that rules using type information take longer to run. -See [Linting with Type Information](/docs/linting/typed-linting) for more details. -::: - -### `strict` - -Additional strict rules that can also catch bugs but are more opinionated than recommended rules. - -```json -{ - "extends": [ - "plugin:@typescript-eslint/recommended", - "plugin:@typescript-eslint/recommended-requiring-type-checking", - "plugin:@typescript-eslint/strict" - ] -} -``` - -:::tip -We recommend a TypeScript project extend from this configuration only if a nontrivial percentage of its developers are highly proficient in TypeScript. -::: - -## Overriding Configurations - -These configurations are our recommended starting points, but **you don't need to use them as-is**. -ESLint allows you to configure your own rule settings on top of any extended configurations. -See [ESLint's Configuring Rules docs](https://eslint.org/docs/user-guide/configuring/rules#using-configuration-files). - -### Suggesting Configuration Changes - -If you feel strongly that a specific rule should (or should not) be one of these configurations, please [file an issue](https://github.com/typescript-eslint/typescript-eslint/issues/new?assignees=&labels=package%3A+eslint-plugin%2Cpreset+config+change%2Ctriage&template=09-config-change.yaml&title=Configs%3A+%3Ca+short+description+of+my+proposal%3E) along with a **detailed** argument explaining your reasoning. - -## Prettier - -If you use [`prettier`](https://www.npmjs.com/package/prettier), there is also a helpful config to help ensure ESLint doesn't report on formatting issues that prettier will fix: [`eslint-config-prettier`](https://www.npmjs.com/package/eslint-config-prettier). - -Using this config by adding it to the end of your `extends`: - -```js title=".eslintrc.js" -module.exports = { - root: true, - parser: '@typescript-eslint/parser', - plugins: ['@typescript-eslint'], - extends: [ - 'eslint:recommended', - 'plugin:@typescript-eslint/recommended', - // Add this line - 'prettier', - ], -}; -``` - -:::warning -**We strongly recommend you use Prettier or an equivalent**, not ESLint formatting rules. -See [this issue](https://github.com/typescript-eslint/typescript-eslint/issues/4907 'Issue: Docs: Add our opinion on delegating stylistic issues to a tool such as Prettier #4907') for more information. -::: diff --git a/docs/linting/CONFIGURATIONS.mdx b/docs/linting/CONFIGURATIONS.mdx new file mode 100644 index 000000000000..eebf58cf8fd2 --- /dev/null +++ b/docs/linting/CONFIGURATIONS.mdx @@ -0,0 +1,141 @@ +--- +id: configs +title: Configurations +--- + +[ESLint shareable configurations](https://eslint.org/docs/latest/developer-guide/shareable-configs) exist to provide a comprehensive base config for you. +`@typescript-eslint/eslint-plugin` includes built-in configurations you can extend from to pull in the recommended starting rules. + +> With the exception of `strict`, all configurations are considered "stable". +> Rule additions and removals are treated as breaking changes and will only be done in major version bumps. + +## Recommended Configurations + +Most projects should extend from at least one of: + +- [`recommended`](#recommended): Recommended rules for code correctness that you can drop in without additional configuration. +- [`recommended-requiring-type-checking`](#recommended-requiring-type-checking): Additional recommended rules that require type information. +- [`strict`](#strict): Additional strict rules that can also catch bugs but are more opinionated than recommended rules. + +:::tip +We recommend most projects use [`recommended-requiring-type-checking`](#recommended-requiring-type-checking) (which requires [typed linting](./TYPED_LINTING.md)). +::: + +:::note +These configurations are our recommended starting points, but **you don't need to use them as-is**. +ESLint allows configuring own rule settings on top of extended configurations. +See [ESLint's Configuring Rules docs](https://eslint.org/docs/user-guide/configuring/rules#using-configuration-files). +::: + +### `recommended` + +Recommended rules for code correctness that you can drop in without additional configuration. +These rules are those whose reports are almost always for a bad practice and/or likely bug. +`recommended` also disables rules known to conflict with this repository, or cause issues in TypeScript codebases. + +```json +{ + "extends": ["plugin:@typescript-eslint/recommended"] +} +``` + +See [`configs/recommended.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/recommended.ts) for the exact contents of this config. + +:::tip +We strongly recommend all TypeScript projects extend from `plugin:@typescript-eslint/recommended`. +::: + +### `recommended-requiring-type-checking` + +Additional recommended rules that require type information. +Rules in this configuration are similarly useful to those in `recommended`. + +```json +{ + "extends": [ + "plugin:@typescript-eslint/recommended", + "plugin:@typescript-eslint/recommended-requiring-type-checking" + ] +} +``` + +See [`configs/recommended-requiring-type-checking.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/recommended-requiring-type-checking.ts) for the exact contents of this config. + +:::tip +We recommend all TypeScript projects extend from `plugin:@typescript-eslint/recommended-requiring-type-checking`, with the caveat that rules using type information take longer to run. +See [Linting with Type Information](/docs/linting/typed-linting) for more details. +::: + +### `strict` + +Additional strict rules that can also catch bugs but are more opinionated than recommended rules. + +```json +{ + "extends": [ + "plugin:@typescript-eslint/recommended", + "plugin:@typescript-eslint/recommended-requiring-type-checking", + "plugin:@typescript-eslint/strict" + ] +} +``` + +See [`configs/strict.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/strict.ts) for the exact contents of this config. + +:::caution +We recommend a TypeScript project extend from `plugin:@typescript-eslint/strict` only if a nontrivial percentage of its developers are highly proficient in TypeScript. +::: + +## Other Configurations + +TypeScript ESLint includes a scattering of utility configurations used by the recommended configurations. +We don't recommend using these directly; instead, extend from an earlier recommended rule. + +### `all` + +Enables each the rules provided as a part of TypeScript ESLint. +Note that many rules are not applicable in all codebases, or are meant to be configured. + +See [`configs/all.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/all.ts) for the exact contents of this config. + +:::warning +We do not recommend a TypeScript projects extend from `plugin:@typescript-eslint/all`. +Many rules conflict with each other and/or are intended to be configured per-project. +::: + +### `base` + +A minimal ruleset that sets only the required parser and plugin options needed to run TypeScript ESLint. + + + +This config is automatically included if you use any of the recommended configurations. + +### `eslint-recommended` + +This ruleset is meant to be used after extending `eslint:recommended`. +It disables core ESLint rules that are already checked by the TypeScript compiler. +Additionally, it enables rules that promote using the more modern constructs TypeScript allows for. + +```jsonc +{ + "extends": [ + "eslint:recommended", + "plugin:@typescript-eslint/eslint-recommended" + ] +} +``` + +This config is automatically included if you use any of the recommended configurations. + +See [`configs/eslint-recommended.ts``](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/eslint-recommended.ts) for the exact contents of this config. + +## Suggesting Configuration Changes + +If you feel strongly that a specific rule should (or should not) be one of these configurations, please [file an issue](https://github.com/typescript-eslint/typescript-eslint/issues/new?assignees=&labels=package%3A+eslint-plugin%2Cpreset+config+change%2Ctriage&template=09-config-change.yaml&title=Configs%3A+%3Ca+short+description+of+my+proposal%3E) along with a **detailed** argument explaining your reasoning. + +## Formatting + +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#suggested-usage). diff --git a/docs/linting/troubleshooting/FORMATTING.md b/docs/linting/troubleshooting/FORMATTING.md index 2acb36d0e600..47ff57c3b45c 100644 --- a/docs/linting/troubleshooting/FORMATTING.md +++ b/docs/linting/troubleshooting/FORMATTING.md @@ -27,6 +27,22 @@ Linters typically run on a rule-by-rule basis, typically resulting in many edge We recommend using [`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) to disable formatting rules in your ESLint configuration. You can then configure your formatter separately from ESLint. +Using this config by adding it to the end of your `extends`: + +```js title=".eslintrc.js" +module.exports = { + extends: [ + 'eslint:recommended', + 'plugin:@typescript-eslint/recommended', + // Add this line + 'prettier', + ], + parser: '@typescript-eslint/parser', + plugins: ['@typescript-eslint'], + root: true, +}; +``` + ## ESLint Core and Formatting Per [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies#what-are-the-changes):