diff --git a/docs/Contributing.mdx b/docs/Contributing.mdx index 852e503c2694..922b41a8608d 100644 --- a/docs/Contributing.mdx +++ b/docs/Contributing.mdx @@ -11,5 +11,5 @@ So, from the bottom of our hearts, _thank you_ 💕. ## Getting Started -Please read our [Code of Conduct](https://github.com/typescript-eslint/typescript-eslint/blob/main/CODE_OF_CONDUCT.md) first. -If you're new to open source, you may also find the [How to Contribute to Open Source](https://opensource.guide/how-to-contribute) guide from https://opensource.guide useful. +Please read our [Code of Conduct](https://github.com/typescript-eslint/typescript-eslint/blob/main/CODE_OF_CONDUCT.md) first. +If you're new to open source, you may also find the [How to Contribute to Open Source](https://opensource.guide/how-to-contribute) guide from https://opensource.guide useful. diff --git a/docs/Getting_Started.mdx b/docs/Getting_Started.mdx index 4763b8055a9f..e21de1b7204d 100644 --- a/docs/Getting_Started.mdx +++ b/docs/Getting_Started.mdx @@ -9,7 +9,7 @@ These steps will get you running ESLint with our recommended rules on your TypeS ### 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 this plugin: ```bash npm2yarn npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint typescript @@ -30,7 +30,7 @@ module.exports = { ``` :::info -If your project doesn't use ESM, naming the file as `.eslintrc.js` is fine. See [ESLint's Configuration Files docs](https://eslint.org/docs/user-guide/configuring/configuration-files) for more info. +If your project doesn't use ESM, naming the file as `.eslintrc.js` is fine. See [ESLint's Configuration Files docs](https://eslint.org/docs/user-guide/configuring/configuration-files) for more info. ::: ### Step 3: Running ESLint @@ -76,12 +76,12 @@ ESLint will lint all TypeScript compatible files within the current folder, and ## Next Steps -We provide a plethora of powerful rules that utilize the power of TypeScript's type information. [Visit 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 page for a setup guide](./linting/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](./linting/Troubleshooting.mdx). ### Documentation Resources -- You can read more about configuring ESLint [in their documentation on configuration](https://eslint.org/docs/user-guide/configuring). -- You can read more about the rules provided by ESLint [in their documentation on their rules](https://eslint.org/docs/rules/). -- You can read more about the rules provided by typescript-eslint in [our rules documentation](/rules). +- You can read more about configuring ESLint [in their documentation on configuration](https://eslint.org/docs/user-guide/configuring). +- You can read more about the rules provided by ESLint [in their documentation on their rules](https://eslint.org/docs/rules/). +- You can read more about the rules provided by typescript-eslint in [our rules documentation](/rules). diff --git a/docs/Maintenance.mdx b/docs/Maintenance.mdx index 0d599b38a376..780eeafe0433 100644 --- a/docs/Maintenance.mdx +++ b/docs/Maintenance.mdx @@ -27,13 +27,13 @@ We do our best to roughly adhere to this model - though at times we may shortcut ### Changes to Governance -Any changes to this document will be posted for open discussion on the [typescript-eslint GitHub Discussions](https://github.com/typescript-eslint/typescript-eslint/discussions) and kept open for at least one month. +Any changes to this document will be posted for open discussion on the [typescript-eslint GitHub Discussions](https://github.com/typescript-eslint/typescript-eslint/discussions) and kept open for at least one month. The discussion will be shared at the beginning, middle, and end of that month on Discord and all our social media accounts. ## Providing Feedback We're always receptive to suggestions on how to improve our processes! -For general feedback, we'd suggest posting in the [`#development` channel on Discord](https://discord.com/channels/1026804805894672454/1088474511759917106). +For general feedback, we'd suggest posting in the [`#development` channel on Discord](https://discord.com/channels/1026804805894672454/1088474511759917106). We can help you turn that into a GitHub discussion. :::note diff --git a/docs/Packages.mdx b/docs/Packages.mdx index 52406fc6c11e..e7570772d157 100644 --- a/docs/Packages.mdx +++ b/docs/Packages.mdx @@ -3,16 +3,34 @@ id: packages title: Packages --- -The `@typescript-eslint/*` packages are all stored in [our GitHub monorepo](https://github.com/typescript-eslint/typescript-eslint). -The monorepo is built and released with [Nx](https://nx.dev). +The `@typescript-eslint/*` packages are all stored in [our GitHub monorepo](https://github.com/typescript-eslint/typescript-eslint). +The monorepo is built and released with [Nx](https://nx.dev). Each page in this section corresponds to a package we intentionally expose to users. They are: -- [`@typescript-eslint/eslint-plugin`](./packages/ESLint_Plugin.mdx): An ESLint plugin which provides lint rules for TypeScript codebases. -- [`@typescript-eslint/eslint-plugin-tslint`](./packages/ESLint_Plugin_TSLint.mdx): An ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. -- [`@typescript-eslint/parser`](./packages/Parser.mdx): An ESLint parser which allows for ESLint to lint TypeScript source code. -- [`@typescript-eslint/rule-tester`](./packages/Rule_Tester.mdx): A utility for testing ESLint rules. -- [`@typescript-eslint/scope-manager`](./packages/Scope_Manager.mdx): A fork of [`eslint-scope`](https://github.com/eslint/eslint-scope), enhanced to support TypeScript functionality. -- [`@typescript-eslint/typescript-estree`](./packages/TypeScript_ESTree.mdx): The underlying code used by [`@typescript-eslint/parser`](./packages/Parser.mdx) that converts TypeScript source code into an [ESTree](https://github.com/estree/estree)-compatible form. -- [`@typescript-eslint/utils`](./packages/Utils.mdx): Utilities for working with TypeScript + ESLint together. +- [`@typescript-eslint/eslint-plugin`](./packages/ESLint_Plugin.mdx): An + ESLint plugin which provides lint rules for TypeScript codebases. +- + [`@typescript-eslint/eslint-plugin-tslint`](./packages/ESLint_Plugin_TSLint.mdx) + + : An ESLint plugin that allows running TSLint rules within ESLint to help you migrate + from TSLint to ESLint. +- [`@typescript-eslint/parser`](./packages/Parser.mdx): An ESLint parser + which allows for ESLint to lint TypeScript source code. +- [`@typescript-eslint/rule-tester`](./packages/Rule_Tester.mdx): A + utility for testing ESLint rules. +- [`@typescript-eslint/scope-manager`](./packages/Scope_Manager.mdx): A + fork of [`eslint-scope`](https://github.com/eslint/eslint-scope), enhanced + to support TypeScript functionality. +- + [`@typescript-eslint/typescript-estree`](./packages/TypeScript_ESTree.mdx) + + : The underlying code used by + [`@typescript-eslint/parser`](./packages/Parser.mdx) + that converts TypeScript source code into an + [ESTree](https://github.com/estree/estree) + + -compatible form. +- [`@typescript-eslint/utils`](./packages/Utils.mdx): Utilities for + working with TypeScript + ESLint together. diff --git a/docs/contributing/Discussions.mdx b/docs/contributing/Discussions.mdx index 80c723157dda..1e8c1e5587c7 100644 --- a/docs/contributing/Discussions.mdx +++ b/docs/contributing/Discussions.mdx @@ -3,10 +3,10 @@ id: discussions title: Discussions --- -Most proposals in the typescript-eslint repository happen in [GitHub Issues](https://docs.github.com/issues). -We generally try to keep conversations inside issues for their discoverability and ability to be linked to [GitHub Pull Requests](https://docs.github.com/pull-requests). +Most proposals in the typescript-eslint repository happen in [GitHub Issues](https://docs.github.com/issues). +We generally try to keep conversations inside issues for their discoverability and ability to be linked to [GitHub Pull Requests](https://docs.github.com/pull-requests). -We have [GitHub Discussions](https://docs.github.com/discussions) enabled to enable three kinds of deeper, threaded conversations: +We have [GitHub Discussions](https://docs.github.com/discussions) enabled to enable three kinds of deeper, threaded conversations: - **Community Feedback**: Questions from the maintainer team that should be raised to the broader community - **RFCs (Requests For Comments)**: Formalized proposals for larger changes that should be discussed before turned into issues @@ -16,12 +16,12 @@ Before filing a Discussion, search the issue tracker for any related conversatio Link to them in the Discussion, along with a detailed description of what you'd like to discuss. :::tip -For change proposals that match an [existing issue format](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose), keep to filing issues. +For change proposals that match an [existing issue format](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose), keep to filing issues. Most don't need to be moved to this separate format. We can always move an issue to a discussion if it becomes unexpectedly deep. ::: :::caution Please don't use Discussions as a support forum. -See [Contributing > Issues > Questions and Support Requests](./Issues.mdx#questions-and-support-requests). +See [Contributing > Issues > Questions and Support Requests](./Issues.mdx#questions-and-support-requests). ::: diff --git a/docs/contributing/Issues.mdx b/docs/contributing/Issues.mdx index 879600ae5d81..eee828dfcac3 100644 --- a/docs/contributing/Issues.mdx +++ b/docs/contributing/Issues.mdx @@ -8,9 +8,9 @@ Great! Please do: -- Make sure you're using the [latest version of our packages](https://github.com/typescript-eslint/typescript-eslint/releases) -- Search [all opened and closed issues](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+) to make sure your issue wouldn't be a duplicate -- Fill out the [appropriate issue template](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose) completely +- Make sure you're using the [latest version of our packages](https://github.com/typescript-eslint/typescript-eslint/releases) +- Search [all opened and closed issues](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+) to make sure your issue wouldn't be a duplicate +- Fill out the [appropriate issue template](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose) completely - Provide as much information as you can ## Commenting @@ -29,7 +29,7 @@ Please don't: ### Issue Claiming We don't use any kind of issue claiming system. -We've found in the past that they result in accidental ["licked cookie"](https://devblogs.microsoft.com/oldnewthing/20091201-00/?p=15843) situations where contributors claim an issue but run out of time or energy trying before sending a PR. +We've found in the past that they result in accidental ["licked cookie"](https://devblogs.microsoft.com/oldnewthing/20091201-00/?p=15843) situations where contributors claim an issue but run out of time or energy trying before sending a PR. If an issue has been marked as `accepting prs` and an open PR does not exist, feel free to send a PR. You don't need to ask for permission. @@ -39,9 +39,9 @@ You don't need to ask for permission. The issue tracker is not an appropriate place for questions or support requests. You can instead: -- Ask in our [Discord server](https://discord.gg/FSxKq8Tdyg)'s `#help` server -- Ask a question on [StackOverflow](https://stackoverflow.com/questions/tagged/typescript-eslint 'StackOverflow questions tagged with typescript-eslint') using the `typescript-eslint` tag -- Publicly toot [@tseslint on Mastodon](https://fosstodon.org/@tseslint) or tweet [@tseslint on Twitter](https://twitter.com/tseslint) +- Ask in our [Discord server](https://discord.gg/FSxKq8Tdyg)'s `#help` server +- Ask a question on [StackOverflow](https://stackoverflow.com/questions/tagged/typescript-eslint 'StackOverflow questions tagged with typescript-eslint') using the `typescript-eslint` tag +- Publicly toot [@tseslint on Mastodon](https://fosstodon.org/@tseslint) or tweet [@tseslint on Twitter](https://twitter.com/tseslint) > Note that requests to add documentation _are_ allowed, even encouraged! 📝 diff --git a/docs/contributing/Local_Development.mdx b/docs/contributing/Local_Development.mdx index 725e9354b32e..0e51ae8c69e0 100644 --- a/docs/contributing/Local_Development.mdx +++ b/docs/contributing/Local_Development.mdx @@ -5,11 +5,11 @@ title: Local Development Thank you for your interest in developing on typescript-eslint! ❤️‍🔥 -> See [Contributing](../Contributing.mdx) and [Issues](./Issues.mdx) for details on our general contribution flows. +> See [Contributing](../Contributing.mdx) and [Issues](./Issues.mdx) for details on our general contribution flows. ## Setup -After [forking the repo from GitHub](https://help.github.com/articles/fork-a-repo) and [installing Yarn](https://yarnpkg.com): +After [forking the repo from GitHub](https://help.github.com/articles/fork-a-repo) and [installing Yarn](https://yarnpkg.com): ```shell git clone https://github.com//typescript-eslint @@ -34,11 +34,11 @@ For example, if you make a change within `scope-manager` and want to use it in ` The following checks are all run on pull requests automatically. You can also perform them locally. -> See [Contributing > Pull Requests](./Pull_Requests.mdx) for more information on pull requests. +> See [Contributing > Pull Requests](./Pull_Requests.mdx) for more information on pull requests. ### Formatting -We use [Prettier](https://prettier.io) to auto-format code. +We use [Prettier](https://prettier.io) to auto-format code. A Git pre-commit hook should apply it to all committed changes. Alternately, you can run `yarn format` in any package or in the root. @@ -51,15 +51,19 @@ You can run `yarn lint` in any package or in the root. Changes must pass two linters for documentation and naming, the commands for which may be run from the root: -- `yarn check-spelling`: [CSpell](https://cspell.org), for all code -- `yarn lint-markdown`: [Markdownlint](https://github.com/DavidAnson/markdownlint), for Markdown documentation +- `yarn check-spelling`: [CSpell](https://cspell.org), for all code +- `yarn lint-markdown`: [Markdownlint](https://github.com/DavidAnson/markdownlint), for Markdown documentation ### Tests All code changes should ideally be unit tested if possible. You can run `yarn test` in any package to run its tests. -> [VS Code launch tasks](https://code.visualstudio.com/docs/editor/tasks) tasks are provided that allow [visual debugging](https://code.visualstudio.com/docs/editor/debugging) tests. +> +> [VS Code launch tasks](https://code.visualstudio.com/docs/editor/tasks) +> tasks are provided that allow +> [visual debugging](https://code.visualstudio.com/docs/editor/debugging) +> tests. #### Code Coverage @@ -87,7 +91,7 @@ You can run `yarn typecheck` in any package or in the root to run `tsc`. ## Website Development -Our interactive documentation website is built with [Docusaurus](https://docusaurus.io). +Our interactive documentation website is built with [Docusaurus](https://docusaurus.io). Running `yarn start` from either the root or `packages/website` will start a local dev server on `localhost:3000`. > The `website` package relies on other packages being built. diff --git a/docs/contributing/Pull_Requests.mdx b/docs/contributing/Pull_Requests.mdx index 4a6194c64a03..ca6b622aca67 100644 --- a/docs/contributing/Pull_Requests.mdx +++ b/docs/contributing/Pull_Requests.mdx @@ -3,17 +3,17 @@ id: pull-requests title: Pull Requests --- -> See [Local Development](./Local_Development.mdx) for details on how to get started developing locally. +> See [Local Development](./Local_Development.mdx) for details on how to get started developing locally. So you've got changes locally that address an issue? Fantastic! Please do: -- Only send pull requests that resolve [open issues marked as `accepting prs`](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+is%3Aopen+label%3A%22accepting+prs%22) +- Only send pull requests that resolve [open issues marked as `accepting prs`](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+is%3Aopen+label%3A%22accepting+prs%22) - One exception: extremely minor documentation typos - Fill out the pull request template in full -- Validate your changes per [Development > Validating Changes](./Local_Development.mdx#validating-changes) before un-[drafting your PR](https://github.blog/2019-02-14-introducing-draft-pull-requests) +- Validate your changes per [Development > Validating Changes](./Local_Development.mdx#validating-changes) before un-[drafting your PR](https://github.blog/2019-02-14-introducing-draft-pull-requests) Please don't: @@ -23,7 +23,7 @@ Please don't: - Reasoning: Your PR hasn't been forgotten! The volunteer maintainers have limited time to work on the project, and they will get to it as soon as they are able. - One exception: if a PR has been blocked on a question to a maintainer for 3 or more months, please ping us - we probably lost track of it. - Comment on a closed PR - - Reasoning: It is much easier for maintainers to not lose track of things if they are posted as issues. If you think there's a bug in typescript-eslint, the right way to ask is to [file a new issue](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose). The issue templates include helpful & necessary practices such as making sure you're on the latest version of all our packages. You can provide the link to the relevant PR to add more context. + - Reasoning: It is much easier for maintainers to not lose track of things if they are posted as issues. If you think there's a bug in typescript-eslint, the right way to ask is to [file a new issue](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose). The issue templates include helpful & necessary practices such as making sure you're on the latest version of all our packages. You can provide the link to the relevant PR to add more context. ### Raising a PR @@ -34,7 +34,7 @@ The title of your PR should match the following format: (): ``` -You can find more samples of good past PR titles in [recent commits to `main`](https://github.com/typescript-eslint/typescript-eslint/commits/main): +You can find more samples of good past PR titles in [recent commits to `main`](https://github.com/typescript-eslint/typescript-eslint/commits/main): - `fix(scope-manager): correct handling for class static blocks` - `docs: fix links to getting started in README.md` @@ -45,7 +45,7 @@ Within the body of your PR, make sure you reference the issue that you have work > Feel free to commit in whatever style you feel comfortable with. > Tip: Send the PR from a branch other than `main`. -> See GitHub's [Proposing Changes docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests) for more information. +> See GitHub's [Proposing Changes docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests) for more information. #### type @@ -71,16 +71,16 @@ A succinct title for the PR. ### Addressing Feedback and Beyond -With your PR raised and the CI passing, your PR will [wait in the queue to be reviewed](https://github.com/typescript-eslint/typescript-eslint/pulls?q=is%3Apr+is%3Aopen+sort%3Acreated-asc+-label%3A%22breaking+change%22+-label%3A%22awaiting+response%22+-label%3A%221+approval%22+-label%3A%22DO+NOT+MERGE%22+status%3Asuccess). +With your PR raised and the CI passing, your PR will [wait in the queue to be reviewed](https://github.com/typescript-eslint/typescript-eslint/pulls?q=is%3Apr+is%3Aopen+sort%3Acreated-asc+-label%3A%22breaking+change%22+-label%3A%22awaiting+response%22+-label%3A%221+approval%22+-label%3A%22DO+NOT+MERGE%22+status%3Asuccess). We generally review PRs oldest to newest, unless we consider a newer PR higher priority (e.g. if it's a bug fix). Once we have reviewed your PR, we will provide any feedback that needs addressing. If you feel a requested change is wrong, don't be afraid to discuss with us in the comments. -Please post comments as [line comments](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#adding-line-comments-to-a-pull-request) when possible, so that they can be threaded. -You can [resolve conversations](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#resolving-conversations) on your own when you feel they're resolved - no need to comment explicitly and/or wait for a maintainer. +Please post comments as [line comments](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#adding-line-comments-to-a-pull-request) when possible, so that they can be threaded. +You can [resolve conversations](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#resolving-conversations) on your own when you feel they're resolved - no need to comment explicitly and/or wait for a maintainer. -Once you've addressed all our feedback by making code changes and/or started a followup discussion, [re-request review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews#re-requesting-a-review) from each maintainer whose feedback you addressed. +Once you've addressed all our feedback by making code changes and/or started a followup discussion, [re-request review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews#re-requesting-a-review) from each maintainer whose feedback you addressed. Once the feedback is addressed, and the PR is approved, we'll ensure the branch is up to date with `main`, and merge it for you. diff --git a/docs/contributing/local-development/Local_Linking.mdx b/docs/contributing/local-development/Local_Linking.mdx index 00908758485c..e884775bbe8e 100644 --- a/docs/contributing/local-development/Local_Linking.mdx +++ b/docs/contributing/local-development/Local_Linking.mdx @@ -23,10 +23,10 @@ done The command to put instead of that `#` comment, depends on the local downstream repository's package manager: -- [npm](https://docs.npmjs.com/cli/v9/commands/npm-link 'npm link docs'): `npm link` -- [pnpm](https://pnpm.io/cli/link 'pnpm link docs'): `pnpm link --global` -- [Yarn v1 / classic](https://classic.yarnpkg.com/lang/en/docs/cli/link/ 'Yarn v1 / classic docs'): `yarn link` -- [Yarn v2 / v3 / berry](https://yarnpkg.com/cli/link 'Yarn v2 / v3 / berry docs'): _skip this step altogether_ +- [npm](https://docs.npmjs.com/cli/v9/commands/npm-link): `npm link` +- [pnpm](https://pnpm.io/cli/link): `pnpm link --global` +- [Yarn v1 / classic](https://classic.yarnpkg.com/lang/en/docs/cli/link/): `yarn link` +- [Yarn v2 / v3 / berry](https://yarnpkg.com/cli/link): _skip this step altogether_ ## Repository Linking diff --git a/docs/developers/Custom_Rules.mdx b/docs/developers/Custom_Rules.mdx index d0494bdd0c33..1ed5ed43cc45 100644 --- a/docs/developers/Custom_Rules.mdx +++ b/docs/developers/Custom_Rules.mdx @@ -6,7 +6,7 @@ title: Custom Rules :::important This page describes how to write your own custom ESLint rules using typescript-eslint. -You should be familiar with [ESLint's developer guide](https://eslint.org/docs/developer-guide) and [ASTs](/blog/asts-and-typescript-eslint) before writing custom rules. +You should be familiar with [ESLint's developer guide](https://eslint.org/docs/developer-guide) and [ASTs](/blog/asts-and-typescript-eslint) before writing custom rules. ::: As long as you are using `@typescript-eslint/parser` as the `parser` in your ESLint configuration, custom ESLint rules generally work the same way for JavaScript and TypeScript code. @@ -18,7 +18,7 @@ The main three changes to custom rules writing are: ## Utils Package -The [`@typescript-eslint/utils`](../packages/Utils.mdx) package acts as a replacement package for `eslint` that exports all the same objects and types, but with typescript-eslint support. +The [`@typescript-eslint/utils`](../packages/Utils.mdx) package acts as a replacement package for `eslint` that exports all the same objects and types, but with typescript-eslint support. It also exports common utility functions and constants most custom typescript-eslint rules tend to use. :::caution @@ -227,7 +227,7 @@ export function describeNode(node: TSESTree.Node): string { ### Explicit Node Types -Rule queries that use more features of [esquery](https://github.com/estools/esquery) such as targeting multiple node types may not be able to infer the type of the `node`. +Rule queries that use more features of [esquery](https://github.com/estools/esquery) such as targeting multiple node types may not be able to infer the type of the `node`. In that case, it is best to add an explicit type declaration. This rule snippet targets name nodes of both function and interface declarations: @@ -256,7 +256,7 @@ export const rule = createRule({ ## Typed Rules :::tip -Read TypeScript's [Compiler APIs > Type Checker APIs](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API#type-checker-apis) for how to use a program's type checker. +Read TypeScript's [Compiler APIs > Type Checker APIs](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API#type-checker-apis) for how to use a program's type checker. ::: The biggest addition typescript-eslint brings to ESLint rules is the ability to use TypeScript's type checker APIs. @@ -336,7 +336,7 @@ Consider either gating type checking behind an explicit option for the rule or c `@typescript-eslint/rule-tester` exports a `RuleTester` with a similar API to the built-in ESLint `RuleTester`. It should be provided with the same `parser` and `parserOptions` you would use in your ESLint configuration. -Below is a quick-start guide. For more in-depth docs and examples [see the `@typescript-eslint/rule-tester` package documentation](../packages/Rule_Tester.mdx). +Below is a quick-start guide. For more in-depth docs and examples [see the `@typescript-eslint/rule-tester` package documentation](../packages/Rule_Tester.mdx). ### Testing Untyped Rules diff --git a/docs/linting/Configurations.mdx b/docs/linting/Configurations.mdx index 1a777b2bcf40..1050dd33175b 100644 --- a/docs/linting/Configurations.mdx +++ b/docs/linting/Configurations.mdx @@ -3,8 +3,11 @@ id: configs title: Configurations --- -[ESLint shareable configurations](https://eslint.org/docs/latest/developer-guide/shareable-configs) exist to provide a comprehensive list of rules settings that you can start with. -`@typescript-eslint/eslint-plugin` includes built-in configurations you can extend from to pull in the recommended starting rules. +[ESLint shareable +configurations](https://eslint.org/docs/latest/developer-guide/shareable-configs) +exist to provide a comprehensive list of rules settings that you can start with. +`@typescript-eslint/eslint-plugin` includes built-in configurations you can extend +from to pull in the recommended starting rules. > With the exception of `all`, `strict`, and `strict-type-checked`, all configurations are considered "stable". > Rule additions and removals are treated as breaking changes and will only be done in major version bumps. @@ -13,7 +16,7 @@ title: Configurations ### 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](./Typed_Linting.mdx), we suggest enabling the [`recommended`](#recommended) and [`stylistic`](#stylistic) configurations to start: ```js title=".eslintrc.js" module.exports = { @@ -29,7 +32,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](./Typed_Linting.mdx), we suggest enabling the [`recommended-type-checked`](#recommended-type-checked) and [`stylistic-type-checked`](#stylistic-type-checked) configurations to start: ```js title=".eslintrc.js" module.exports = { @@ -61,7 +64,7 @@ We recommend that most projects should extend from either: :::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). +See [ESLint's Configuring Rules docs](https://eslint.org/docs/user-guide/configuring/rules#using-configuration-files). ::: ### `recommended` @@ -76,7 +79,7 @@ module.exports = { }; ``` -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. +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. ### `recommended-type-checked` @@ -89,7 +92,7 @@ module.exports = { }; ``` -See [`configs/recommended-type-checked.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/recommended-type-checked.ts) for the exact contents of this config. +See [`configs/recommended-type-checked.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/recommended-type-checked.ts) for the exact contents of this config. ### `strict` @@ -102,7 +105,7 @@ module.exports = { }; ``` -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. +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. @@ -119,7 +122,7 @@ module.exports = { }; ``` -See [`configs/strict-type-checked.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/strict-type-checked.ts) for the exact contents of this config. +See [`configs/strict-type-checked.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/strict-type-checked.ts) for the exact contents of this config. :::caution We recommend a TypeScript project extend from `plugin:@typescript-eslint/strict-type-checked` only if a nontrivial percentage of its developers are highly proficient in TypeScript. @@ -136,7 +139,7 @@ module.exports = { }; ``` -See [`configs/stylistic.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/stylistic.ts) for the exact contents of this config. +See [`configs/stylistic.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/stylistic.ts) for the exact contents of this config. ### `stylistic-type-checked` @@ -149,7 +152,7 @@ module.exports = { }; ``` -See [`configs/stylistic-type-checked.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/stylistic-type-checked.ts) for the exact contents of this config. +See [`configs/stylistic-type-checked.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/stylistic-type-checked.ts) for the exact contents of this config. ## Other Configurations @@ -160,7 +163,7 @@ typescript-eslint includes a few utility configurations. 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. +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 TypeScript projects extend from `plugin:@typescript-eslint/all`. @@ -174,14 +177,14 @@ We don't recommend using this directly; instead, extend from an earlier recommen This config is automatically included if you use any of the recommended configurations. -See [`configs/base.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/base.ts) for the exact contents of this config. +See [`configs/base.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/base.ts) for the exact contents of this config. ### `disable-type-checked` A utility ruleset that will disable type-aware linting and all type-aware rules available in our project. -This config is useful if you'd like to have your base config concerned with type-aware linting, and then conditionally use [overrides](https://eslint.org/docs/latest/use/configure/configuration-files#configuration-based-on-glob-patterns) to disable type-aware linting on specific subsets of your codebase. +This config is useful if you'd like to have your base config concerned with type-aware linting, and then conditionally use [overrides](https://eslint.org/docs/latest/use/configure/configuration-files#configuration-based-on-glob-patterns) to disable type-aware linting on specific subsets of your codebase. -See [`configs/disable-type-checked.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/disable-type-checked.ts) for the exact contents of this config. +See [`configs/disable-type-checked.ts`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/configs/disable-type-checked.ts) for the exact contents of this config. :::info If you use type-aware rules from other plugins, you will need to manually disable these rules or use a premade config they provide to disable them. @@ -219,14 +222,14 @@ module.exports = { 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. +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. +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.mdx#suggested-usage---prettier). +See [What About Formatting? > Suggested Usage](./troubleshooting/Formatting.mdx#suggested-usage---prettier). diff --git a/docs/linting/Troubleshooting.mdx b/docs/linting/Troubleshooting.mdx index 526a79e03c63..30ee75db1dda 100644 --- a/docs/linting/Troubleshooting.mdx +++ b/docs/linting/Troubleshooting.mdx @@ -7,7 +7,7 @@ title: Troubleshooting & FAQs This happens because TypeScript adds new features that ESLint doesn't know about. -The first step is to [check our list of "extension" rules here](/rules/#extension-rules). +The first step is to [check our list of "extension" rules here](/rules/#extension-rules). An extension rule is a rule which extends the base ESLint rules to support TypeScript syntax. If you find it in there, give it a go to see if it works for you. You can configure it by disabling the base rule, and turning on the extension rule. @@ -23,10 +23,13 @@ Here's an example with the `semi` rule: ``` If you don't find an existing extension rule, or the extension rule doesn't work for your case, then you can go ahead and check our issues. -[The contributing guide outlines the best way to raise an issue](../contributing/Issues.mdx). + +[The contributing guide outlines the best way to raise an +issue](../contributing/Issues.mdx) +. > We release a new version our tooling every week. -> _Please_ ensure that you [check our the latest list of "extension" rules](/rules/#extension-rules) **_before_** filing an issue. +> _Please_ ensure that you [check our the latest list of "extension" rules](/rules/#extension-rules) **_before_** filing an issue. ## I get errors telling me "ESLint was configured to run ... However, that TSConfig does not / none of those TSConfigs include this file" @@ -37,10 +40,10 @@ 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. + - 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: + - 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 @@ -82,9 +85,9 @@ These errors are caused by an ESLint config requesting type information be gener 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** want to lint the file with [type-aware linting](./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 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) @@ -97,9 +100,9 @@ This error may appear from the combination of two things: - The ESLint configuration for the source file specifies at least one TSConfig file in `parserOptions.project` - None of those TSConfig files includes the source file being linted - - Note that files with the same name and different extension may not be recognized by TypeScript: see [`parserOptions.project` docs](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsproject) + - Note that files with the same name and different extension may not be recognized by TypeScript: see [`parserOptions.project` docs](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsproject) -When TSConfig files are specified for parsing a source file, `@typescript-eslint/parser` will use the first TSConfig that is able to include that source file (per [aka.ms/tsconfig#include](https://www.typescriptlang.org/tsconfig#include)) to generate type information. +When TSConfig files are specified for parsing a source file, `@typescript-eslint/parser` will use the first TSConfig that is able to include that source file (per [aka.ms/tsconfig#include](https://www.typescriptlang.org/tsconfig#include)) to generate type information. However, if no specified TSConfig includes the source file, the parser won't be able to generate type information. This error most commonly happens on config files or similar that are not included in their project TSConfig(s). @@ -110,7 +113,7 @@ For example, many projects have files like: 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`. -See our docs on [type aware linting](./Typed_Linting.mdx) for more information. +See our docs on [type aware linting](./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,10 +124,13 @@ 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. -- [Checkout ESLint's documentation on configuring rules](https://eslint.org/docs/latest/use/configure/rules) to ensure you understand how to configure rules. +- [Read our getting started guide](../Getting_Started.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. +Our [rule docs](/rules) detail the options each rule supports under the "Options" heading. We use TypeScript types to describe an `Options` tuple type for the rule which you can use to configure the a rule. In your config file the keys of the `rules` object are the names of the rules you wish to configure and the values follow the following form: @@ -157,7 +163,7 @@ module.exports = { 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. -If the IDE also shows that the type is never nullish / is `any`, you need to fix the type. A very common case is with the [`no-unnecessary-condition`](/rules/no-unnecessary-condition) rule. Take this code for example: +If the IDE also shows that the type is never nullish / is `any`, you need to fix the type. A very common case is with the [`no-unnecessary-condition`](/rules/no-unnecessary-condition) rule. Take this code for example: ```ts let condition = false; @@ -191,7 +197,7 @@ 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. +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", @@ -202,13 +208,13 @@ If you are running into issues parsing .vue files, it might be because parsers l } ``` -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. +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 This is to be expected - ESLint rules do not check file extensions on purpose, as it causes issues in environments that use non-standard extensions (for example, a `.vue` and a `.md` file can both contain TypeScript code to be linted). -If you have some pure JavaScript code that you do not want to apply certain lint rules to, then you can use [ESLint's `overrides` configuration](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns) to turn off certain rules, or even change the parser based on glob patterns. +If you have some pure JavaScript code that you do not want to apply certain lint rules to, then you can use [ESLint's `overrides` configuration](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns) to turn off certain rules, or even change the parser based on glob patterns. ## Should I run ESLint on transpiled output JavaScript files? @@ -221,14 +227,14 @@ There's no benefit to also linting output JavaScript files. Make sure that you have installed TypeScript locally i.e. by using `npm install typescript`, not `npm install -g typescript`, or by using `yarn add typescript`, not `yarn global add typescript`. -See [#2041](https://github.com/typescript-eslint/typescript-eslint/issues/2041) for more information. +See [#2041](https://github.com/typescript-eslint/typescript-eslint/issues/2041) for more information. ## How can I ban ``? -ESLint core contains the rule [`no-restricted-syntax`](https://eslint.org/docs/rules/no-restricted-syntax). -This generic rule allows you to specify a [selector](https://eslint.org/docs/developer-guide/selectors) for the code you want to ban, along with a custom error message. +ESLint core contains the rule [`no-restricted-syntax`](https://eslint.org/docs/rules/no-restricted-syntax). +This generic rule allows you to specify a [selector](https://eslint.org/docs/developer-guide/selectors) for the code you want to ban, along with a custom error message. -You can use an AST visualization tool such as [typescript-eslint playground](/play#showAST=es) > _Options_ > _AST Explorer_ on its left sidebar by selecting _ESTree_ to help in figuring out the structure of the AST that you want to ban. +You can use an AST visualization tool such as [typescript-eslint playground](/play#showAST=es) > _Options_ > _AST Explorer_ on its left sidebar by selecting _ESTree_ to help in figuring out the structure of the AST that you want to ban. For example, you can ban enums (or some variation of) using one of the following configs: @@ -296,7 +302,7 @@ 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). +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? @@ -313,7 +319,7 @@ You can check what versions are installed in your project using the following co npm list @typescript-eslint/eslint-plugin @typescript-eslint/parser ``` -If you see more than one version installed, then you will have to either use [yarn resolutions](https://classic.yarnpkg.com/en/docs/selective-version-resolutions) to force a single version, or you will have to downgrade your root versions to match the dependency versions. +If you see more than one version installed, then you will have to either use [yarn resolutions](https://classic.yarnpkg.com/en/docs/selective-version-resolutions) to force a single version, or you will have to downgrade your root versions to match the dependency versions. **The best course of action in this case is to wait until your dependency releases a new version with support for our latest versions.** @@ -328,7 +334,7 @@ For example: - `@typescript-eslint/strict-boolean-expressions` might be operating with TypeScript version _X_ and think a variable is `string[] | undefined` - TypeScript itself might be on version _X+1-beta_ and think the variable is `string[]` -See [this issue comment](https://github.com/typescript-eslint/typescript-eslint/issues/4102#issuecomment-963265514) for more details. +See [this issue comment](https://github.com/typescript-eslint/typescript-eslint/issues/4102#issuecomment-963265514) for more details. ## Changes to one file are not reflected when linting other files in my IDE @@ -338,16 +344,18 @@ ESLint currently does not have any way of telling parsers such as ours when an a That means if you change file A that is imported by file B, it won't update lint caches for file B -- even if file B's text contents have changed. Sometimes the only solution is to restart your ESLint editor extension altogether. -See [this issue comment](https://github.com/typescript-eslint/typescript-eslint/issues/5845#issuecomment-1283248238 'GitHub issue 5845, comment 1283248238: details on ESLint cross-file caching') for more information. +See [this issue comment](https://github.com/typescript-eslint/typescript-eslint/issues/5845#issuecomment-1283248238 'GitHub issue 5845, comment 1283248238: details on ESLint cross-file caching') for more information. :::tip -[VS Code's ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) provides an `ESLint: Restart ESLint Server` action. -::: + +[VS Code's ESLint +extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) +provides an `ESLint: Restart ESLint Server` action. ::: ### I get `no-unsafe-*` complaints for cross-file changes See [Changes to one file are not reflected in linting other files in my IDE](#changes-to-one-file-are-not-reflected-when-linting-other-files-in-my-ide). -Rules such as [`no-unsafe-argument`](/rules/no-unsafe-argument), [`no-unsafe-assignment`](/rules/no-unsafe-assignment), and [`no-unsafe-call`](/rules/no-unsafe-call) are often impacted. +Rules such as [`no-unsafe-argument`](/rules/no-unsafe-argument), [`no-unsafe-assignment`](/rules/no-unsafe-assignment), and [`no-unsafe-call`](/rules/no-unsafe-call) are often impacted. ## "The '``' property is deprecated on '``' nodes. Use '``' instead." warnings @@ -356,7 +364,7 @@ Make sure you're using the latest versions of each of your ESLint plugins (and o If you've using many ESLint plugins, have updated each to their latest version, and you're not sure which one this complaint is coming from, try either or both of: -- Running with [`--trace-deprecation`](https://nodejs.org/api/cli.html#--trace-deprecation) (e.g. `npx cross-env NODE_OPTIONS=--trace-deprecation npm run lint`) +- Running with [`--trace-deprecation`](https://nodejs.org/api/cli.html#--trace-deprecation) (e.g. `npx cross-env NODE_OPTIONS=--trace-deprecation npm run lint`) - Disabling half of them at a time to narrow down which plugin it is Then make sure each of those plugins has a GitHub issue asking that they release a version supporting typescript-eslint v6. @@ -371,16 +379,16 @@ 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. +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](https://deploy-preview-6515--typescript-eslint.netlify.app/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? No, TypeScript project references are not yet supported. -See [issue #2094 discussing project references](https://github.com/typescript-eslint/typescript-eslint/issues/2094) for more details. +See [issue #2094 discussing project references](https://github.com/typescript-eslint/typescript-eslint/issues/2094) for more details. diff --git a/docs/linting/Typed_Linting.mdx b/docs/linting/Typed_Linting.mdx index 066077bbf779..b6f8a235523d 100644 --- a/docs/linting/Typed_Linting.mdx +++ b/docs/linting/Typed_Linting.mdx @@ -30,15 +30,15 @@ module.exports = { :::caution Your `.eslintrc.cjs` 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.mdx#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). ::: 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](./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)). + - 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)). With that done, run the same lint command you ran before. You may see new rules reporting errors based on type information! @@ -62,17 +62,17 @@ module.exports = { }; ``` -See [the `@typescript-eslint/parser` docs for more details](../packages/Parser.mdx#project). +See [the `@typescript-eslint/parser` docs for more details](../packages/Parser.mdx#project). :::note -If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx). +If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx). ::: ## FAQs ### How can I disable type-aware linting for a subset of files? -You can combine ESLint's [overrides](https://eslint.org/docs/latest/use/configure/configuration-files#configuration-based-on-glob-patterns) config in conjunction with our [`disable-type-checked`](./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`](./Configurations.mdx#disable-type-checked) config to turn off type-aware linting on specific subsets of files. ```js title=".eslintrc.js" module.exports = { @@ -118,8 +118,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.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.mdx). diff --git a/docs/linting/troubleshooting/Formatting.mdx b/docs/linting/troubleshooting/Formatting.mdx index 57d1562ebb72..6705ab8a6ddb 100644 --- a/docs/linting/troubleshooting/Formatting.mdx +++ b/docs/linting/troubleshooting/Formatting.mdx @@ -4,7 +4,7 @@ title: What About Formatting? --- We recommend against using ESLint for formatting. -We recommend using [Prettier](https://prettier.io), [dprint](https://dprint.dev), or an equivalent instead. +We recommend using [Prettier](https://prettier.io), [dprint](https://dprint.dev), or an equivalent instead. ## Formatters vs. Linters @@ -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](../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. @@ -35,7 +35,7 @@ This design allows formatters to be much more comprehensive and consistent at mu Neither typescript-eslint nor ESLint core enable any formatting-related rules in any recommended presets. However, some third party plugin configurations may still enable that bad practice. -If you see formatting rules enabled in your ESLint configuration, we recommend using [`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) to disable formatting rules in your ESLint configuration. +If you see formatting rules enabled in your ESLint configuration, 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`: @@ -60,12 +60,12 @@ Note that even if you use a formatter other than `prettier`, you can use `eslint #### `eslint-plugin-prettier` -`eslint-config-prettier` is not the same as [`eslint-plugin-prettier`](https://github.com/prettier/eslint-plugin-prettier). +`eslint-config-prettier` is not the same as [`eslint-plugin-prettier`](https://github.com/prettier/eslint-plugin-prettier). - 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-troubleshooting#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 @@ -76,7 +76,7 @@ Most lint rules fall into one of two to three categories: - **Stylistic**: Rules that care about style concerns which do impact runtime behavior of code, but generally not logic. These are mostly around naming or which roughly-equivalent syntax constructs to use (such as function declarations vs. arrow functions). - **Formatting**: Stylistic rules that care only about trivia (semicolons, whitespace, etc.) without impacting the runtime behavior of the code. These rules conflict with dedicated formatters such as Prettier. -Per [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies#what-are-the-changes), ESLint itself has moved away from _stylistic_ rules, including _formatting_ rules: +Per [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies#what-are-the-changes), ESLint itself has moved away from _stylistic_ rules, including _formatting_ rules: > Stylistic rules are frozen - we won't be adding any more options to stylistic rules. > We've learned that there's no way to satisfy everyone's personal preferences, and most of the rules already have a lot of difficult-to-understand options. @@ -88,9 +88,9 @@ With the exception of bug fixes, no new formatting- or stylistic-related pull re ## `eslint-stylistic` The downside of using a comprehensive formatter for formatting is that it will strictly apply opinions to code. -Although you can [ignore code in Prettier](https://prettier.io/docs/en/ignore.html) and other formatters, including inline such as with [`// prettier-ignore` comments](https://prettier.io/docs/en/ignore.html#javascript), formatters are much more opinionated than lint rules. +Although you can [ignore code in Prettier](https://prettier.io/docs/en/ignore.html) and other formatters, including inline such as with [`// prettier-ignore` comments](https://prettier.io/docs/en/ignore.html#javascript), formatters are much more opinionated than lint rules. -The [`eslint-stylistic`](https://eslint.style) project provides an ESLint plugin containing _formatting_ and _stylistic_ rules. +The [`eslint-stylistic`](https://eslint.style) project provides an ESLint plugin containing _formatting_ and _stylistic_ rules. That plugin can serve as your formatter if you strongly prefer not to use a dedicated formatter. -See [ESLint Stylistic > Why?](https://eslint.style/guide/why) for more details on that project's motivation, and [ESLint Stylistic > Getting Started](https://eslint.style/guide/getting-started) for how to set it up. +See [ESLint Stylistic > Why?](https://eslint.style/guide/why) for more details on that project's motivation, and [ESLint Stylistic > Getting Started](https://eslint.style/guide/getting-started) for how to set it up. diff --git a/docs/linting/troubleshooting/Performance.mdx b/docs/linting/troubleshooting/Performance.mdx index ec90afca02eb..1cdf65728497 100644 --- a/docs/linting/troubleshooting/Performance.mdx +++ b/docs/linting/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](../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. @@ -43,7 +43,7 @@ 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. +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 @@ -51,9 +51,9 @@ This rule helps ensure your codebase follows a consistent indentation pattern. However this involves a _lot_ of computations across every single token in a file. Across a large codebase, these can add up, and severely impact performance. -We recommend not using this rule, and instead using a tool like [`prettier`](https://www.npmjs.com/package/prettier) to enforce a standardized formatting. +We recommend not using this rule, and instead using a tool like [`prettier`](https://www.npmjs.com/package/prettier) to enforce a standardized formatting. -See our [documentation on formatting](./Formatting.mdx) for more information. +See our [documentation on formatting](./Formatting.mdx) for more information. ## `eslint-plugin-prettier` @@ -69,7 +69,7 @@ For example, our CI is setup to run the following command automatically, which b npm run prettier --check . ``` -See [Prettier's `--check` docs](https://prettier.io/docs/en/cli#--check) for more details. +See [Prettier's `--check` docs](https://prettier.io/docs/en/cli#--check) for more details. ## `eslint-plugin-import` @@ -105,7 +105,7 @@ If you want to enforce file extensions are always used and you **ARE** using `mo On the surface `import/extensions` seems like it should be fast for this use case, however the rule isn't just a pure AST-check - it has to resolve modules on disk so that it doesn't false positive on cases where you are importing modules with an extension as part of their name (eg `foo.js` resolves to `node_modules/foo.js/index.js`, so the `.js` is required). This disk lookup is costly and thus makes the rule slow. -If your project doesn't use any `npm` packages with a file extension in their name, nor do you name your files with two extensions (like `bar.js.ts`), then this extra cost probably isn't worth it, and you can use a much simpler check using the [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax) lint rule. +If your project doesn't use any `npm` packages with a file extension in their name, nor do you name your files with two extensions (like `bar.js.ts`), then this extra cost probably isn't worth it, and you can use a much simpler check using the [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax) lint rule. The below config is several orders of magnitude faster than `import/extensions` as it does not do disk lookups, however it will false-positive on cases like the aforementioned `foo.js` module. diff --git a/docs/linting/troubleshooting/TSLint.mdx b/docs/linting/troubleshooting/TSLint.mdx index 29e778aec936..b38448fc2fe2 100644 --- a/docs/linting/troubleshooting/TSLint.mdx +++ b/docs/linting/troubleshooting/TSLint.mdx @@ -10,14 +10,14 @@ TSLint was a linter equivalent to ESLint that was written specifically to work d ## Migrating from TSLint to ESLint -The standard tool to convert a TSLint configuration to the equivalent ESLint configuration is [`tslint-to-eslint-config`](https://github.com/typescript-eslint/tslint-to-eslint-config). +The standard tool to convert a TSLint configuration to the equivalent ESLint configuration is [`tslint-to-eslint-config`](https://github.com/typescript-eslint/tslint-to-eslint-config). If you are still using TSLint, we strongly recommend you use this tool to switch. -You can look at [the alternatives list](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/TSLINT_RULE_ALTERNATIVES.md) for an up to date overview of how TSLint rules compare to the ones in this package. +You can look at [the alternatives list](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/TSLINT_RULE_ALTERNATIVES.md) for an up to date overview of how TSLint rules compare to the ones in this package. 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? @@ -26,7 +26,7 @@ Unfortunately, that meant TSLint couldn't reuse any of the previous work which h TSLint had to reimplement everything from editor extensions to auto-fixing to rules. TSLint's backers announced in 2019 that **they would be deprecating TSLint in favor of supporting `typescript-eslint`** in order to benefit the community. -You can read more about that here: https://medium.com/palantir/tslint-in-2019-1a144c2317a9. +You can read more about that here: https://medium.com/palantir/tslint-in-2019-1a144c2317a9. The TypeScript team also migrated the TypeScript codebase from TSLint to `typescript-eslint`, and they have been supporters of this project. -See more details at https://github.com/microsoft/TypeScript/issues/30553. +See more details at https://github.com/microsoft/TypeScript/issues/30553. diff --git a/docs/linting/typed-linting/Monorepos.mdx b/docs/linting/typed-linting/Monorepos.mdx index 43f688062b79..31bbbaa85944 100644 --- a/docs/linting/typed-linting/Monorepos.mdx +++ b/docs/linting/typed-linting/Monorepos.mdx @@ -38,8 +38,8 @@ Be sure to update your `.eslintrc.js` to point at this new config file. ## One `tsconfig.json` per package (and an optional one in the root) -The `parserOptions.project` option introduced in [Linting with Type Information](../Typed_Linting.mdx) accepts an array of relative paths. -Paths may be provided as [Node globs](https://github.com/isaacs/node-glob/blob/f5a57d3d6e19b324522a3fa5bdd5075fd1aa79d1/README.md#glob-primer). +The `parserOptions.project` option introduced in [Linting with Type Information](../Typed_Linting.mdx) accepts an array of relative paths. +Paths may be provided as [Node globs](https://github.com/isaacs/node-glob/blob/f5a57d3d6e19b324522a3fa5bdd5075fd1aa79d1/README.md#glob-primer). For each file being linted, the first matching project path will be used as its backing TSConfig. ```js title=".eslintrc.js" @@ -89,14 +89,14 @@ 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. +See [Glob pattern in parser's option "project" slows down linting](https://github.com/typescript-eslint/typescript-eslint/issues/2611) for more details. ### Important note regarding large (> 10) multi-package monorepos We've had reports that for sufficiently large and/or interdependent projects, you may run into OOMs using this approach. Our advice is to set it up and test first, as there are very few cases that trigger this OOM. -See [#1192](https://github.com/typescript-eslint/typescript-eslint/issues/1192) for more information and discussion. +See [#1192](https://github.com/typescript-eslint/typescript-eslint/issues/1192) for more information and discussion. If you do run into an OOM, please comment on the above issue and let us know about your repo - the more information we have, the better. As an interim workaround, consider one of the following: @@ -106,4 +106,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.mdx). diff --git a/docs/maintenance/Branding.mdx b/docs/maintenance/Branding.mdx index d4e84d90deae..9355952dcd2f 100644 --- a/docs/maintenance/Branding.mdx +++ b/docs/maintenance/Branding.mdx @@ -29,7 +29,7 @@ Combining lowercase with a dash helps differentiate us. Our primary brand color is `#2656c7`, the halfway point between ESLint's `#4b32c3` purple and TypeScript's `#007acc` blue. You can call it _blurple_ if you want. -Our logo is also a halfway between [ESLint's logo](https://en.wikipedia.org/wiki/ESLint#/media/File:ESLint_logo.svg) and [TypeScript's logo](https://en.wikipedia.org/wiki/TypeScript#/media/File:Typescript.svg): +Our logo is also a halfway between [ESLint's logo](https://en.wikipedia.org/wiki/ESLint#/media/File:ESLint_logo.svg) and [TypeScript's logo](https://en.wikipedia.org/wiki/TypeScript#/media/File:Typescript.svg): typescript-eslint logo -- [Logo PNG download](/img/logo.png) -- [Logo SVG download](/img/logo.svg) +- [Logo PNG download](/img/logo.png) +- [Logo SVG download](/img/logo.svg) diff --git a/docs/maintenance/Contributor_Tiers.mdx b/docs/maintenance/Contributor_Tiers.mdx index aebf7ebe20d2..9beccaf22186 100644 --- a/docs/maintenance/Contributor_Tiers.mdx +++ b/docs/maintenance/Contributor_Tiers.mdx @@ -140,7 +140,7 @@ Any other activities (e.g. responding to Discord threads, working on upstream de ## Advancement Each tier corresponds to a role on Discord and GitHub. -When you first hit a tier, you can post in the [`#roles` channel on Discord](https://discord.com/channels/1026804805894672454/1184219870691328051). +When you first hit a tier, you can post in the [`#roles` channel on Discord](https://discord.com/channels/1026804805894672454/1184219870691328051). We will confirm privately that you've hit the intent of the contribution tiers. We'll then grant you the role on Discord and GitHub and profusely thank you for everything you've done. ❤️ @@ -168,7 +168,7 @@ Each month: - Committers and maintainers who hit their expectation receive their full shares - Committers and maintainers who hit roughly half their expectation receive half shares -Reimbursements are generally handled through [our Open Collective page](https://opencollective.com/typescript-eslint). +Reimbursements are generally handled through [our Open Collective page](https://opencollective.com/typescript-eslint). ### Community Reimbursements diff --git a/docs/maintenance/Issues.mdx b/docs/maintenance/Issues.mdx index 52794f3e7e70..8d8c31263c4e 100644 --- a/docs/maintenance/Issues.mdx +++ b/docs/maintenance/Issues.mdx @@ -3,7 +3,7 @@ id: issues title: Issues --- -This document serves as a guide for how you might manage our [GitHub Issues](https://docs.github.com/issues), also known as issue triaging. +This document serves as a guide for how you might manage our [GitHub Issues](https://docs.github.com/issues), also known as issue triaging. Use your best judgement when triaging issues, and most of all remember to be **encouraging, friendly, and kind** when responding to users. Many users are new to open source and/or typed linting. @@ -15,7 +15,7 @@ If you're ever unsure on any part of issue management, don't hesitate to loop in ## Governance -Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#pointing): +Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#pointing): - Straightforward: at reviewer discretion, may be marked as approved by any committer or maintainer. This includes docs enhancements, bug fixes, and feature additions. @@ -27,14 +27,19 @@ Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#poin ## Issue Flow :::note -We include a set of common responses to issues in [`.github/replies.yml`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/replies.yml), intended to be used with the [Refined Saved Replies](https://github.com/JoshuaKGoldberg/refined-saved-replies) extension. +We include a set of common responses to issues in [`.github/replies.yml`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/replies.yml), intended to be used with the [Refined Saved Replies](https://github.com/JoshuaKGoldberg/refined-saved-replies) extension. Don't treat these as exact responses you must use: they're just a starting copy+paste helper. Please do adopt your specific responses to your personal tone and to match the thread for non-straightforward issues. ::: -[Issues pending triage](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3Atriage) are searchable with the `triage` label. -That label is added automatically when a new issue is created. -Most issues go through the following review flow when created or updated: + + + [Issues pending + triage](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3Atriage) + + are searchable with the `triage` label. That label is added automatically when +a new issue is created. Most issues go through the following review flow when created +or updated: 1. A maintainer ensures the issue is valid: - If the poster didn't fill out an appropriate template with enough information: @@ -48,8 +53,13 @@ Most issues go through the following review flow when created or updated: - Add the `working as intended` label and remove the `bug` and `triage` labels - If the behavior is due to the user doing something wrong, such as an incorrect config: - Add the `fix: user error` label - - [This issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22fix%3A+user+error%22+is%3Aclosed) - - If the behavior is otherwise expected, [this issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22working+as+intended%22+-label%3A%22fix%3A+user+error%22+is%3Aclosed+) + - + + [This issue search has some examples of closing + comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22fix%3A+user+error%22+is%3Aclosed) + + + - If the behavior is otherwise expected, [this issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22working+as+intended%22+-label%3A%22fix%3A+user+error%22+is%3Aclosed+) - You needn't go into too much detail in your comment - just enough to explain it 2. If the report is valid, add the `accepting prs` label and remove the `triage` label 3. If you know the rough steps for a fix, consider writing a comment with links to codebase to help someone put together a fix @@ -89,7 +99,7 @@ In such cases you can forgo the back-and-forth and just skip to the closing step #### 🐞 "Simple" Bugs -A simple bug is a bug that can be reproduced in a single TS file plus an ESLint config (and possibly a TSConfig) - i.e. an issue reproducible on [our playground](/play). +A simple bug is a bug that can be reproduced in a single TS file plus an ESLint config (and possibly a TSConfig) - i.e. an issue reproducible on [our playground](/play). The vast majority of bug reports fall into this category. If you cannot reproduce the issue as described using the issue's provided playground reproduction, it has not provided enough information. @@ -116,7 +126,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](../linting/troubleshooting/Formatting.mdx)) #### ✨ Rule Enhancements @@ -131,18 +141,18 @@ We have two common strategies for them: - Add an option to disable the new logic: which is a breaking change if opt-in, and a non-breaking change if opt-out - Add an option to enable the new logic: which is a breaking change if opt-out, and a non-breaking change if opt-in -See [Can we standardize logical direction of rule options?](https://github.com/typescript-eslint/typescript-eslint/discussions/6101) for context on naming options. +See [Can we standardize logical direction of rule options?](https://github.com/typescript-eslint/typescript-eslint/discussions/6101) for context on naming options. -For enhancements meant to limit which kinds of nodes the rule targets, mark the issue as blocked on [RFC: Common format to specify a type or value as a rule option](https://github.com/typescript-eslint/typescript-eslint/discussions/6017). +For enhancements meant to limit which kinds of nodes the rule targets, mark the issue as blocked on [RFC: Common format to specify a type or value as a rule option](https://github.com/typescript-eslint/typescript-eslint/discussions/6017). #### 🚀 New Rules We're generally accepting of new rules that meet the above feature request criteria. -The biggest exception is rules that can roughly be implemented with [`@typescript-eslint/ban-types`](/rules/ban-types) and/or [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax). +The biggest exception is rules that can roughly be implemented with [`@typescript-eslint/ban-types`](/rules/ban-types) and/or [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax). ## Pruning Old Issues -Every so often, we like to [search for open issues `awaiting response`](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3A%22awaiting+response%22) to find ones that might have been forgotten. +Every so often, we like to [search for open issues `awaiting response`](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3A%22awaiting+response%22) to find ones that might have been forgotten. Our flow for issues that have been waiting for >=1 month is: 1. Ping the author with a message like the _Checking In_ template diff --git a/docs/maintenance/Pull_Requests.mdx b/docs/maintenance/Pull_Requests.mdx index 4ed8fa9c513f..23a01c4ceee2 100644 --- a/docs/maintenance/Pull_Requests.mdx +++ b/docs/maintenance/Pull_Requests.mdx @@ -15,7 +15,7 @@ If you're ever unsure on any part of PR reviews, don't hesitate to loop in a mai ## Governance -Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#pointing): +Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#pointing): - Straightforward: At reviewer discretion, may be merged with a single approval by any committer or maintainer. This includes docs enhancements, bug fixes, and feature additions. @@ -27,7 +27,7 @@ Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#poin ## PR Flow :::note -We include a set of common responses to PRs in [`.github/replies.yml`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/replies.yml), intended to be used with the [Refined Saved Replies](https://github.com/JoshuaKGoldberg/refined-saved-replies) extension. +We include a set of common responses to PRs in [`.github/replies.yml`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/replies.yml), intended to be used with the [Refined Saved Replies](https://github.com/JoshuaKGoldberg/refined-saved-replies) extension. Don't treat these as exact responses you must use: they're just a starting copy+paste helper. Please do adopt your specific responses to your personal tone and to match the thread for non-straightforward PRs. ::: @@ -36,7 +36,7 @@ TODO: This will be filled out... soon! ## Pruning Old PRs -Every so often, we like to [search for open PRs `awaiting response`](https://github.com/typescript-eslint/typescript-eslint/pulls?q=is%3Aopen+is%3Apr+label%3A%22awaiting+response%22) to find ones that might have been forgotten. +Every so often, we like to [search for open PRs `awaiting response`](https://github.com/typescript-eslint/typescript-eslint/pulls?q=is%3Aopen+is%3Apr+label%3A%22awaiting+response%22) to find ones that might have been forgotten. Our flow for PRs that have been waiting for >=1 month is: 1. Ping the author with a message like the _Checking In_ template @@ -50,4 +50,4 @@ Consider adding fun to PR reviews with GIFs. The benefits of using GIFs in PR reviews are that it adds a touch of humor and lightheartedness to the process, builds camaraderie and team spirit, and can help break the ice by making users feel welcomed. Please remember to use appropriate and respectful GIFs and use them sparingly; GIFs should enhance the conversation, not detract from it. -> We like to use the _GIFs for Github_ extension: available as [GIFs for GitHub (Chrome)](https://chrome.google.com/webstore/detail/gifs-for-github/dkgjnpbipbdaoaadbdhpiokaemhlphep) and [GIFs for GitHub (Firefox)](https://addons.mozilla.org/en-US/firefox/addon/gifs-for-github). ✨ +> We like to use the _GIFs for Github_ extension: available as [GIFs for GitHub (Chrome)](https://chrome.google.com/webstore/detail/gifs-for-github/dkgjnpbipbdaoaadbdhpiokaemhlphep) and [GIFs for GitHub (Firefox)](https://addons.mozilla.org/en-US/firefox/addon/gifs-for-github). ✨ diff --git a/docs/maintenance/Releases.mdx b/docs/maintenance/Releases.mdx index 651624b77e36..6d78133e6b04 100644 --- a/docs/maintenance/Releases.mdx +++ b/docs/maintenance/Releases.mdx @@ -5,24 +5,25 @@ title: Releases {/* TODO: update references to lerna to be `nx release instead` */} -[Users > Releases](../users/Releases.mdx) describes how our automatic releases are done. -There is generally no maintenance activity we need to take for the weekly releases. +[Users > Releases](../users/Releases.mdx) describes how our automatic releases +are done. There is generally no maintenance activity we need to take for the weekly +releases. However, there are two kinds of releases we infrequently go through that each require manual effort. ## Major Releases -Per [Users > Releases > Major Releases](../users/Releases.mdx#major-releases), we infrequently release major versions with accumulated breaking changes. +Per [Users > Releases > Major Releases](../users/Releases.mdx#major-releases), we infrequently release major versions with accumulated breaking changes. ### 1. Pre-Release Preparation -1. Create a milestone by the name of the release [example: [Milestone 6.0.0](https://github.com/typescript-eslint/typescript-eslint/milestone/8)]. -1. If an issue for changes to recommended rule configs doesn't yet exist, create one [example: [Changes to the `recommended` sets for 5.0.0](https://github.com/typescript-eslint/typescript-eslint/issues/5900)]. +1. Create a milestone by the name of the release [example: [Milestone 6.0.0](https://github.com/typescript-eslint/typescript-eslint/milestone/8)]. +1. If an issue for changes to recommended rule configs doesn't yet exist, create one [example: [Changes to the `recommended` sets for 5.0.0](https://github.com/typescript-eslint/typescript-eslint/issues/5900)]. 1. Add any breaking changes intended for the release to that milestone. 1. Create two new branches off `main` in the project repository (not a personal fork): - `v${major}` - `v${major}-canary-auto-release` -1. Raise a PR from `v${major}-canary-auto-release` to `main` modifying the [`ci.yml` workflow](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/workflows/ci.yml) [example: [chore: add auto-canary release for v6](https://github.com/typescript-eslint/typescript-eslint/pull/5883)]: +1. Raise a PR from `v${major}-canary-auto-release` to `main` modifying the [`ci.yml` workflow](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/workflows/ci.yml) [example: [chore: add auto-canary release for v6](https://github.com/typescript-eslint/typescript-eslint/pull/5883)]: - Under `pushes:` at the beginning of the file, add an `- v${major}` list item. - Add a `publish_canary_version_v${major}` step the same as `publish_canary_version` except: - Add the condition: `if: github.ref == 'refs/heads/v${major}'`. @@ -31,13 +32,13 @@ Per [Users > Releases > Major Releases](../users/Releases.mdx#major-releases), w ### 2. Merging Breaking Changes -1. Send a PR from `v${major}` to `main` [example: [v6.0.0](https://github.com/typescript-eslint/typescript-eslint/pull/5886)]. -1. Change all [breaking change PRs](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+is%3Aopen+label%3A%22breaking+change%22) to target the `v${major}` branch. +1. Send a PR from `v${major}` to `main` [example: [v6.0.0](https://github.com/typescript-eslint/typescript-eslint/pull/5886)]. +1. Change all [breaking change PRs](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+is%3Aopen+label%3A%22breaking+change%22) to target the `v${major}` branch. - To signify these changes as breaking, the first line of the PR description must read as `BREAKING CHANGE:`, and second line should briefly summarize the changes. - It is important to note that when merged the commit message must also include `BREAKING CHANGE:` as the first line in order for lerna to recognize it as a breaking change in the release notes. If you miss this it just means more manual work when writing the release documentation. 1. Wait until all required PRs have been merged 1. Let the release wait for **at least 1 week** to allow time for early adopters to help test it and discuss the changes. - - Promote it on the [`@tseslint`](https://twitter.com/tseslint) twitter to get some additional attention. + - Promote it on the [`@tseslint`](https://twitter.com/tseslint) twitter to get some additional attention. 1. Once discussions have settled, rebase merge the PR on top of `main`. :::note @@ -49,12 +50,12 @@ They don't need any special treatment. 1. Discuss with the maintainers to be ready for an [out-of-band](#out-of-band-releases) release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release. 1. Prepare the release notes. Lerna will automatically generate the release notes on GitHub, however this will be disorganized and unhelpful for users. We need to reorganize the release notes so that breaking changes are placed at the top to make them most visible. If any migrations are required, we must list the steps to make it easy for users. - - Example release notes: [`v5.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v5.0.0), [`v4.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v4.0.0), [`v3.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v3.0.0) + - Example release notes: [`v5.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v5.0.0), [`v4.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v4.0.0), [`v3.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v3.0.0) 1. Finally, tweet the release on the `@tseslint` twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release! ## Out-of-Band Releases -Per [Users > Releases > Out-of-Band Releases](../users/Releases.mdx#out-of-band-releases), we may manually trigger a new release for a rare emergency such as a critical regression. +Per [Users > Releases > Out-of-Band Releases](../users/Releases.mdx#out-of-band-releases), we may manually trigger a new release for a rare emergency such as a critical regression. If that happens: 1. Mention in any relevant issue(s) that you intend to release an out-of-band release diff --git a/docs/maintenance/issues/Rule_Deprecations.mdx b/docs/maintenance/issues/Rule_Deprecations.mdx index 1e89880390b6..3ce5c7e88b4e 100644 --- a/docs/maintenance/issues/Rule_Deprecations.mdx +++ b/docs/maintenance/issues/Rule_Deprecations.mdx @@ -14,7 +14,7 @@ In these cases, we aim to remove the old rule with minimal user disruption. ## Filing the Issue -Rule deprecations can be filed as a [new issue bypassing templates](https://github.com/typescript-eslint/typescript-eslint/issues/new). +Rule deprecations can be filed as a [new issue bypassing templates](https://github.com/typescript-eslint/typescript-eslint/issues/new). Provide it an `## Overview` containing: @@ -23,12 +23,12 @@ Provide it an `## Overview` containing: - Whether it exists in popular configs such as `eslint-config-airbnb-typescript` and `eslint-config-standard-with-typescript` - Sourcegraph queries showing how often it appears in user configs -> See [#6036](https://github.com/typescript-eslint/typescript-eslint/issues/6036) for examples of those links and queries. +> See [#6036](https://github.com/typescript-eslint/typescript-eslint/issues/6036) for examples of those links and queries. ## Timeline -1. In any minor/patch version, add [rule `meta` properties](https://eslint.org/docs/latest/developer-guide/working-with-rules#rule-basics): +1. In any minor/patch version, add [rule `meta` properties](https://eslint.org/docs/latest/developer-guide/working-with-rules#rule-basics): - `deprecated: true` - `replacedBy`, if applicable 2. In the next major version, you may delete the rule - - If the rule is relatively popular with users, consider leaving a documentation page as a tombstone pointing to the new relevant rule or docs (see [`camelcase`](/rules/camelcase/) as an example) + - If the rule is relatively popular with users, consider leaving a documentation page as a tombstone pointing to the new relevant rule or docs (see [`camelcase`](/rules/camelcase/) as an example) diff --git a/docs/maintenance/pull-requests/Dependency_Version_Upgrades.mdx b/docs/maintenance/pull-requests/Dependency_Version_Upgrades.mdx index 73d4e4fbed2d..ab60051651c4 100644 --- a/docs/maintenance/pull-requests/Dependency_Version_Upgrades.mdx +++ b/docs/maintenance/pull-requests/Dependency_Version_Upgrades.mdx @@ -20,7 +20,11 @@ The typescript-eslint repository contains four kinds of version ranges for the ` - Integration tests: Pinned to our lowest supported ESLint version - Packages with a `*` `peerDependency` version: These fall back to the explicit `peerDependency` versions - Packages with explicit `peerDependency` versions: The full range of supported ESLint major versions -- [Root `package.json`](https://github.com/typescript-eslint/typescript-eslint/blob/main/package.json)'s' `devDependency`: A relatively recent release, used only for repository development +- + [Root + `package.json`](https://github.com/typescript-eslint/typescript-eslint/blob/main/package.json) + + 's' `devDependency`: A relatively recent release, used only for repository development :::tip Whenever you discover any new areas of work that are blocked by dropping an old ESLint version, such as new ESLint API deprecations, add a _TODO_ comment that will be caught by the regular expressions under [Removing Support for an Old ESLint Version](#removing-support-for-an-old-eslint-version). @@ -30,8 +34,8 @@ Whenever you discover any new areas of work that are blocked by dropping an old 1. Upgrade the root `package.json` `devDependency` to the latest ESLint 1. Add the new major version to the explicit `peerDependency` versions -1. Check [`eslint-visitor-keys`](https://www.npmjs.com/package/eslint-visitor-keys) for a new version to be upgraded to as well. -1. Update [Users > Dependency Versions > ESLint](../../users/Dependency_Versions.mdx#eslint) +1. Check [`eslint-visitor-keys`](https://www.npmjs.com/package/eslint-visitor-keys) for a new version to be upgraded to as well. +1. Update [Users > Dependency Versions > ESLint](../../users/Dependency_Versions.mdx#eslint) ### Removing Support for an Old ESLint Version @@ -42,9 +46,9 @@ Whenever you discover any new areas of work that are blocked by dropping an old - `/eslint.*5/i` - `/todo.*eslint.*5/i` - `/todo.*eslint/i` -1. Update [Users > Dependency Versions > ESLint](../../users/Dependency_Versions.mdx#eslint) +1. Update [Users > Dependency Versions > ESLint](../../users/Dependency_Versions.mdx#eslint) -See [chore: drop support for ESLint v6](https://github.com/typescript-eslint/typescript-eslint/pull/5972) for reference. +See [chore: drop support for ESLint v6](https://github.com/typescript-eslint/typescript-eslint/pull/5972) for reference. ## Node @@ -56,7 +60,7 @@ The typescript-eslint repository contains three kinds of version ranges for Node Change those numbers accordingly when adding support for a new Node version or removing support for an old Node version. -See [feat: drop support for node v12](https://github.com/typescript-eslint/typescript-eslint/pull/5918) + [chore: test node v14 on ci.yml](https://github.com/typescript-eslint/typescript-eslint/pull/5512) for reference. +See [feat: drop support for node v12](https://github.com/typescript-eslint/typescript-eslint/pull/5918) + [chore: test node v14 on ci.yml](https://github.com/typescript-eslint/typescript-eslint/pull/5512) for reference. ## TypeScript @@ -102,11 +106,16 @@ We generally start the process of supporting a new TypeScript version just after See for reference (caveat: these don't follow the exact process described here): -- [TypeScript 4.7 Support](https://github.com/typescript-eslint/typescript-eslint/issues/4800) -- [TypeScript 4.8 Support](https://github.com/typescript-eslint/typescript-eslint/issues/5227) -- [feat: support TypeScript 4.8](https://github.com/typescript-eslint/typescript-eslint/pull/5551) -- [feat: support TypeScript 4.9](https://github.com/typescript-eslint/typescript-eslint/pull/5716) -- [chore: bump TS from 4.9RC to 4.9](https://github.com/typescript-eslint/typescript-eslint/commit/a40a311bb52a2b1cfac43851b201f8cfc96c8d5d) +- [TypeScript 4.7 + Support](https://github.com/typescript-eslint/typescript-eslint/issues/4800) +- [TypeScript 4.8 + Support](https://github.com/typescript-eslint/typescript-eslint/issues/5227) +- [feat: support TypeScript + 4.8](https://github.com/typescript-eslint/typescript-eslint/pull/5551) +- [feat: support TypeScript + 4.9](https://github.com/typescript-eslint/typescript-eslint/pull/5716) +- [chore: bump TS from 4.9RC to + 4.9](https://github.com/typescript-eslint/typescript-eslint/commit/a40a311bb52a2b1cfac43851b201f8cfc96c8d5d) ### Removing Support for an Old TypeScript Version @@ -115,7 +124,7 @@ A single PR can remove support for old TypeScript versions as a breaking change: 1. Update the root `package.json` `devDependency` 1. Update the `SUPPORTED_TYPESCRIPT_VERSIONS` constant in `warnAboutTSVersion.ts` 1. Update the `versions` constant in `version-check.ts` -1. Update [Users > Dependency Versions > TypeScript](../../users/Dependency_Versions.mdx#typescript) +1. Update [Users > Dependency Versions > TypeScript](../../users/Dependency_Versions.mdx#typescript) 1. Search for source code comments (excluding `CHANGELOG.md` files) that mention a now-unsupported version of TypeScript. - For example, to remove support for v4.3, searches might include: - `4.3` @@ -125,4 +134,4 @@ A single PR can remove support for old TypeScript versions as a breaking change: - `/todo.*ts/i` - `/todo.*typescript/i` -See [feat: bump minimum supported TS version to 4.2.4](https://github.com/typescript-eslint/typescript-eslint/pull/5915). +See [feat: bump minimum supported TS version to 4.2.4](https://github.com/typescript-eslint/typescript-eslint/pull/5915). diff --git a/docs/packages/ESLint_Plugin.mdx b/docs/packages/ESLint_Plugin.mdx index 6db78ddfcebe..fcc194c9d188 100644 --- a/docs/packages/ESLint_Plugin.mdx +++ b/docs/packages/ESLint_Plugin.mdx @@ -8,15 +8,15 @@ 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.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. -Those rules rely on [`@typescript-eslint/parser`](./Parser.mdx) to parse TypeScript code into ESLint-compatible nodes, as well as provide backing TypeScript programs. +Those rules rely on [`@typescript-eslint/parser`](./Parser.mdx) to parse TypeScript code into ESLint-compatible nodes, as well as provide backing TypeScript programs. ## Exports -| Name | Description | -| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `configs` | Object mapping string names of configs to extendable [ESLint config settings](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#extending-configuration-files). | -| `rules` | Object mapping string names of rules to the [rule objects](https://eslint.org/docs/latest/developer-guide/working-with-rules). | +| Name | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `configs` | Object mapping string names of configs to extendable [ESLint config settings](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#extending-configuration-files). | +| `rules` | Object mapping string names of rules to the [rule objects](https://eslint.org/docs/latest/developer-guide/working-with-rules). | diff --git a/docs/packages/ESLint_Plugin_TSLint.mdx b/docs/packages/ESLint_Plugin_TSLint.mdx index 525b1c072477..8941e88c0bfa 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?](../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. ::: ## Installation diff --git a/docs/packages/Parser.mdx b/docs/packages/Parser.mdx index 5d5860493103..ce6b9ef9c5b7 100644 --- a/docs/packages/Parser.mdx +++ b/docs/packages/Parser.mdx @@ -5,7 +5,7 @@ sidebar_label: parser # `@typescript-eslint/parser` -> An [ESLint parser](https://eslint.org/docs/user-guide/configuring/plugins#specifying-parser) used to parse TypeScript code into ESLint-compatible nodes, as well as provide backing TypeScript programs. ✨ +> An [ESLint parser](https://eslint.org/docs/user-guide/configuring/plugins#specifying-parser) used to parse TypeScript code into ESLint-compatible nodes, as well as provide backing TypeScript programs. ✨ This is necessary because TypeScript produces a different, incompatible AST format to the one that ESLint requires to work. For example, this is not valid JavaScript code because it contains the `: number` type annotation: @@ -21,12 +21,12 @@ TS's AST is optimized for its use case of parsing incomplete code and typechecki ESTree is unoptimized and intended for "general purpose" use-cases of traversing the AST. :::tip -You can select `@typescript-eslint/parser` on the [typescript-eslint playground](/play#showAST=es)'s right sidebar by selecting _ESTree_. +You can select `@typescript-eslint/parser` on the [typescript-eslint playground](/play#showAST=es)'s right sidebar by selecting _ESTree_. ::: ## Configuration -The following additional configuration options are available by specifying them in [`parserOptions`](https://eslint.org/docs/user-guide/configuring/language-options#specifying-parser-options) in your ESLint configuration file. +The following additional configuration options are available by specifying them in [`parserOptions`](https://eslint.org/docs/user-guide/configuring/language-options#specifying-parser-options) in your ESLint configuration file. ```ts interface ParserOptions { @@ -60,13 +60,13 @@ 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](../linting/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. :::tip We've seen `allowAutomaticSingleRunInference` improve linting speed in CI by up to 10-20%. -Our plan is to [enable `allowAutomaticSingleRunInference` by default in an upcoming major version](https://github.com/typescript-eslint/typescript-eslint/issues/8121). +Our plan is to [enable `allowAutomaticSingleRunInference` by default in an upcoming major version](https://github.com/typescript-eslint/typescript-eslint/issues/8121). ::: ### `cacheLifetime` @@ -86,7 +86,7 @@ Optional additional options to describe how to parse the raw syntax. > Default `false`. Enable parsing JSX when `true`. -More details can be found in the [TypeScript handbook's JSX docs](https://www.typescriptlang.org/docs/handbook/jsx.html). +More details can be found in the [TypeScript handbook's JSX docs](https://www.typescriptlang.org/docs/handbook/jsx.html). **NOTE:** this setting does not affect known file types (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`, `.json`) because the TypeScript compiler has its own internal handling for known file extensions. @@ -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](../linting/Typed_Linting.mdx). In other words, you don't have to specify `parserOptions.project` in this case, making the linting process faster. ### `extraFileExtensions` @@ -166,7 +166,7 @@ If you provide `parserOptions.project`, you do not need to set this, as it will > Default `'React'` The identifier that's used for JSX Elements creation (after transpilation). -If you're using a library other than React (like `preact`), then you should change this value. If you are using the [new JSX transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) you can set this to `null`. +If you're using a library other than React (like `preact`), then you should change this value. If you are using the [new JSX transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) you can set this to `null`. This should not be a member expression - just the root identifier (i.e. use `"React"` instead of `"React.createElement"`). @@ -176,7 +176,7 @@ If you provide `parserOptions.project`, you do not need to set this, as it will > Default `['es2018']` -For valid options, see the [TypeScript compiler options](https://www.typescriptlang.org/tsconfig#lib). +For valid options, see the [TypeScript compiler options](https://www.typescriptlang.org/tsconfig#lib). Specifies the TypeScript `lib`s that are available. This is used by the scope analyser to ensure there are global variables declared for the types exposed by TypeScript. @@ -190,7 +190,12 @@ This option allows you to programmatically provide an instance of a TypeScript P This will override any programs that would have been computed from `parserOptions.project`. All linted files must be part of the provided program(s). -[Refer to the TypeScript Wiki for an example on how to write the `resolveModuleNames` function](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API#customizing-module-resolution). + + [Refer to the TypeScript Wiki for an example on how to write the + `resolveModuleNames` + function](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API#customizing-module-resolution) + +. ### `project` @@ -220,7 +225,7 @@ This option allows you to provide a path to your project's `tsconfig.json`. **Th - If you use project references, TypeScript will not automatically use project references to resolve files. This means that you will have to add each referenced tsconfig to the `project` field either separately, or via a glob. -- Note that using wide globs `**` in your `parserOptions.project` may cause performance implications. Instead of globs that use `**` to recursively check all folders, prefer paths that use a single `*` at a time. For more info see [#2611](https://github.com/typescript-eslint/typescript-eslint/issues/2611). +- Note that using wide globs `**` in your `parserOptions.project` may cause performance implications. Instead of globs that use `**` to recursively check all folders, prefer paths that use a single `*` at a time. For more info see [#2611](https://github.com/typescript-eslint/typescript-eslint/issues/2611). - TypeScript will ignore files with duplicate filenames in the same folder (for example, `src/file.ts` and `src/file.js`). TypeScript purposely ignore all but one of the files, only keeping the one file with the highest priority extension (the extension priority order (from highest to lowest) is `.ts`, `.tsx`, `.d.ts`, `.js`, `.jsx`). For more info see #955. @@ -309,7 +314,7 @@ We're hopeful this option will eventually become the standard way to enable type It switches the parser from manually creating TypeScript programs to instead calling the same "project services" API used by editors such as VS Code. However, because it's so new and untested, we're keeping it under the `EXPERIMENTAL_` prefix for at least all of the `6.X` versions. -See [feat(typescript-estree): add EXPERIMENTAL_useProjectService option to use TypeScript project service](https://github.com/typescript-eslint/typescript-eslint/pull/6754) for more information. +See [feat(typescript-estree): add EXPERIMENTAL_useProjectService option to use TypeScript project service](https://github.com/typescript-eslint/typescript-eslint/pull/6754) for more information. ## Utilities diff --git a/docs/packages/Rule_Tester.mdx b/docs/packages/Rule_Tester.mdx index 51f53519e797..4a6cfcc04bf6 100644 --- a/docs/packages/Rule_Tester.mdx +++ b/docs/packages/Rule_Tester.mdx @@ -208,7 +208,7 @@ Be sure to set `RuleTester`'s static properties _before_ calling `new RuleTester #### Mocha -Consider setting up `RuleTester`'s static properties in a [`mochaGlobalSetup` fixture](https://mochajs.org/#global-setup-fixtures): +Consider setting up `RuleTester`'s static properties in a [`mochaGlobalSetup` fixture](https://mochajs.org/#global-setup-fixtures): ```ts import * as mocha from 'mocha'; @@ -219,7 +219,7 @@ RuleTester.afterAll = mocha.after; #### Vitest -Consider setting up `RuleTester`'s static properties in a [`setupFiles` script](https://vitest.dev/config/#setupfiles): +Consider setting up `RuleTester`'s static properties in a [`setupFiles` script](https://vitest.dev/config/#setupfiles): ```ts import * as vitest from 'vitest'; diff --git a/docs/packages/Scope_Manager.mdx b/docs/packages/Scope_Manager.mdx index cd33ac0fc751..9ad86dc02fac 100644 --- a/docs/packages/Scope_Manager.mdx +++ b/docs/packages/Scope_Manager.mdx @@ -5,7 +5,7 @@ sidebar_label: scope-manager # `@typescript-eslint/scope-manager` -> A fork of [`eslint-scope`](https://github.com/eslint/eslint-scope), enhanced to support TypeScript functionality. ✨ +> A fork of [`eslint-scope`](https://github.com/eslint/eslint-scope), enhanced to support TypeScript functionality. ✨ A "scope analyser" traverses an AST and builds a model of how variables (and in our case, types) are defined and consumed by the source code. This form of static analysis allows you to understand and trace variables throughout the program, allowing you to access powerful information about a program without needing to drop into the much, much heavier type information. @@ -91,6 +91,7 @@ const scope = analyze(ast, { ## References -- [You can view the original BSD 2 license for the code here](https://github.com/eslint/eslint-scope/blob/dbddf14d5771b21b5da704213e4508c660ca1c64/LICENSE) +- [You can view the original BSD 2 license for the code + here](https://github.com/eslint/eslint-scope/blob/dbddf14d5771b21b5da704213e4508c660ca1c64/LICENSE) - https://eslint.org/docs/developer-guide/scope-manager-interface - https://github.com/eslint/eslint-scope diff --git a/docs/packages/TypeScript_ESTree.mdx b/docs/packages/TypeScript_ESTree.mdx index 27122374bd18..1b0f5daace7c 100644 --- a/docs/packages/TypeScript_ESTree.mdx +++ b/docs/packages/TypeScript_ESTree.mdx @@ -5,14 +5,15 @@ sidebar_label: typescript-estree # `@typescript-eslint/typescript-estree` -> The underlying code used by [`@typescript-eslint/parser`](./Parser.mdx) that converts TypeScript source code into an ESTree-compatible form. ✨ +> The underlying code used by [`@typescript-eslint/parser`](./Parser.mdx) that converts TypeScript source code into an ESTree-compatible form. ✨ This parser is designed to be generic and robust. It can be used to power any use-case which requires taking TypeScript source code and producing an ESTree-compatible AST. It is most known for use within these hyper-popular open-source projects to power their TypeScript support: -- [ESLint](https://eslint.org), the pluggable linting utility for JavaScript and JSX +- [ESLint](https://eslint.org), the pluggable linting utility for + JavaScript and JSX - [Prettier](https://prettier.io), an opinionated code formatter It works by: diff --git a/docs/packages/Utils.mdx b/docs/packages/Utils.mdx index df05daa76909..340e632ed2a1 100644 --- a/docs/packages/Utils.mdx +++ b/docs/packages/Utils.mdx @@ -8,21 +8,21 @@ sidebar_label: utils > Utilities for working with TypeScript + ESLint together. ✨ This package contains public utilities for writing custom rules and plugins in TypeScript. -Rules declared in [`@typescript-eslint/eslint-plugin`](./ESLint_Plugin.mdx) are created using these utility functions. +Rules declared in [`@typescript-eslint/eslint-plugin`](./ESLint_Plugin.mdx) are created using these utility functions. Any custom rules you write generally will be as well. -> See [Custom Rules](../developers/Custom_Rules.mdx) for documentation on creating your own custom ESLint rules for TypeScript code. +> See [Custom Rules](../developers/Custom_Rules.mdx) for documentation on creating your own custom ESLint rules for TypeScript code. ## Exports -| Name | Description | -| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AST_NODE_TYPES` | An enum with the names of every single _node_ found in `TSESTree`. | -| `AST_TOKEN_TYPES` | An enum with the names of every single _token_ found in `TSESTree`. | -| `ASTUtils` | Tools for operating on the ESTree AST. Also includes the [`@eslint-community/eslint-utils`](https://www.npmjs.com/package/@eslint-community/eslint-utils) package, correctly typed to work with the types found in `TSESTree` | -| `ESLintUtils` | Tools for creating ESLint rules with TypeScript. | -| `JSONSchema` | Strict types for the JSON Schema v4 spec - the version that ESLint uses to validate all rules with. | -| `ParserServices` | Typing for the parser services provided when parsing a file using `@typescript-eslint/typescript-estree`. | -| `TSESLint` | Types for ESLint, correctly typed to work with the types found in `TSESTree`. | -| `TSESLintScope` | The [`eslint-scope`](https://www.npmjs.com/package/eslint-scope) package, correctly typed to work with the types found in both `TSESTree` and `TSESLint` | -| `TSESTree` | Types for the TypeScript flavor of ESTree created by `@typescript-eslint/typescript-estree`. | +| Name | Description | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `AST_NODE_TYPES` | An enum with the names of every single _node_ found in `TSESTree`. | +| `AST_TOKEN_TYPES` | An enum with the names of every single _token_ found in `TSESTree`. | +| `ASTUtils` | Tools for operating on the ESTree AST. Also includes the [`@eslint-community/eslint-utils`](https://www.npmjs.com/package/@eslint-community/eslint-utils) package, correctly typed to work with the types found in `TSESTree` | +| `ESLintUtils` | Tools for creating ESLint rules with TypeScript. | +| `JSONSchema` | Strict types for the JSON Schema v4 spec - the version that ESLint uses to validate all rules with. | +| `ParserServices` | Typing for the parser services provided when parsing a file using `@typescript-eslint/typescript-estree`. | +| `TSESLint` | Types for ESLint, correctly typed to work with the types found in `TSESTree`. | +| `TSESLintScope` | The [`eslint-scope`](https://www.npmjs.com/package/eslint-scope) package, correctly typed to work with the types found in both `TSESTree` and `TSESLint` | +| `TSESTree` | Types for the TypeScript flavor of ESTree created by `@typescript-eslint/typescript-estree`. | diff --git a/docs/users/Dependency_Versions.mdx b/docs/users/Dependency_Versions.mdx index 1954306a646a..4c6359dee034 100644 --- a/docs/users/Dependency_Versions.mdx +++ b/docs/users/Dependency_Versions.mdx @@ -13,7 +13,7 @@ We generally support at least the latest two major versions of ESLint. ## Node -This project makes an effort to support Active LTS and Maintenance LTS release statuses of Node according to [Node's release document](https://github.com/nodejs/release#release-schedule). +This project makes an effort to support Active LTS and Maintenance LTS release statuses of Node according to [Node's release document](https://github.com/nodejs/release#release-schedule). Support for specific Current status releases are considered periodically. ## TypeScript @@ -25,7 +25,7 @@ Support for specific Current status releases are considered periodically.

-Note that we mirror [DefinitelyTyped's version support window](https://github.com/DefinitelyTyped/DefinitelyTyped/#support-window) - meaning we only support versions of TypeScript less than 2 years old. +Note that we mirror [DefinitelyTyped's version support window](https://github.com/DefinitelyTyped/DefinitelyTyped/#support-window) - meaning we only support versions of TypeScript less than 2 years old. You may find that our tooling works on older TypeScript versions however we provide no guarantees and **_we will not accept issues against unsupported versions_**. @@ -35,7 +35,7 @@ In some cases, we may even be able to support additional pre-releases (i.e. beta ### Supporting New TypeScript Releases -With each new TypeScript release we file an issue to track the changes in the new version. The issue should always be pinned, and you can also [find the issues by searching for issues tagged with "New TypeScript Version"](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+label%3A%22New+TypeScript+Version%22+sort%3Acreated-desc). If the issue is open, we do not have official support yet - please be patient. +With each new TypeScript release we file an issue to track the changes in the new version. The issue should always be pinned, and you can also [find the issues by searching for issues tagged with "New TypeScript Version"](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+label%3A%22New+TypeScript+Version%22+sort%3Acreated-desc). If the issue is open, we do not have official support yet - please be patient. In terms of what versions we support: @@ -51,8 +51,8 @@ Note that our packages have an open `peerDependency` requirement in order to all If you use a non-supported version of TypeScript, the parser will log a warning to the console. If you want to disable this warning, you can configure this in your `parserOptions`. -See: [Packages > Parser > `warnOnUnsupportedTypeScriptVersion`](../packages/Parser.mdx#warnonunsupportedtypescriptversion). +See: [Packages > Parser > `warnOnUnsupportedTypeScriptVersion`](../packages/Parser.mdx#warnonunsupportedtypescriptversion). ## Dependant Version Upgrades -See [Maintenance > Dependent Version Upgrades](../maintenance/pull-requests/Dependency_Version_Upgrades.mdx) for maintenance steps to update these versions. +See [Maintenance > Dependent Version Upgrades](../maintenance/pull-requests/Dependency_Version_Upgrades.mdx) for maintenance steps to update these versions. diff --git a/docs/users/Releases.mdx b/docs/users/Releases.mdx index 4ad0fdd9db70..6918749718f7 100644 --- a/docs/users/Releases.mdx +++ b/docs/users/Releases.mdx @@ -15,7 +15,7 @@ title: Releases We release a latest version every Monday at 1pm US Eastern time using the latest commit to `main` at that time. This release is performed automatically by a Github action located in a private repository. This release goes to the standard `latest` tag on npm. -See [Versioning](./Versioning.mdx) for how the version number is calculated. +See [Versioning](./Versioning.mdx) for how the version number is calculated. If there have been no commits that impact public-facing packages then a patch-level release shall be released. @@ -23,7 +23,7 @@ Latest releases shall only ever be "minor" or "patch" releases. ### Release Notes -Every release is documented on the [Github Release page](https://github.com/typescript-eslint/typescript-eslint/releases). +Every release is documented on the [Github Release page](https://github.com/typescript-eslint/typescript-eslint/releases). These release notes will list the PRs included in the release. @@ -36,7 +36,7 @@ These release notes will list the PRs included in the release. /> -We release a canary version for each commit to `main` that passes all required checks. This release is performed automatically by the [`publish_canary_version` step](https://github.com/typescript-eslint/typescript-eslint/blob/5feb2dba9da2bd5e233451b7b0f1c99414b5aef9/.github/workflows/ci.yml#L234-L263). So **you never need to wait for a new stable version to make use of any updates**. +We release a canary version for each commit to `main` that passes all required checks. This release is performed automatically by the [`publish_canary_version` step](https://github.com/typescript-eslint/typescript-eslint/blob/5feb2dba9da2bd5e233451b7b0f1c99414b5aef9/.github/workflows/ci.yml#L234-L263). So **you never need to wait for a new stable version to make use of any updates**. This release is goes to the `canary` tag on npm and it is versioned as an incremental canary patch release on top of the current `latest` version. I.e. if the current version is `5.6.1`, then the first canary version will be `5.6.2-alpha.0`, the second `5.6.2-alpha.1`, and so on. @@ -73,7 +73,7 @@ We currently do not have a set schedule around when major releases shall be perf We keep a backlog of breaking issues as a milestone on GitHub that is named in the form `${major}.0.0`. When we do do a major release, we release a release candidate version to the `rc-v${major}` tag on npm for each commit to the major branch. -See [Maintenance > Releases](../maintenance/Releases.mdx#major-releases) for steps to perform a major release. +See [Maintenance > Releases](../maintenance/Releases.mdx#major-releases) for steps to perform a major release. ## Out-of-Band Releases diff --git a/docs/users/Versioning.mdx b/docs/users/Versioning.mdx index f2170a051520..f92649ff7b7c 100644 --- a/docs/users/Versioning.mdx +++ b/docs/users/Versioning.mdx @@ -3,7 +3,7 @@ id: versioning title: Versioning --- -We follow [semantic versioning (semver)](https://semver.org). +We follow [semantic versioning (semver)](https://semver.org). This page exists to help set guidelines around what we consider to fall within each of the semver categories. All of the packages in this project are published with the same version number to make it easier to coordinate both releases and installations.