From 4e554e4d549048362cf07f9d41e3f94ab982e29c Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 25 Jun 2022 12:18:08 -0400 Subject: [PATCH 1/7] chore(website): streamlined Getting Started docs --- _redirects | 4 + docs/README.md | 82 ++++++- docs/development/architecture/PACKAGES.md | 2 +- .../linting/{CONFIGS.md => CONFIGURATIONS.md} | 34 ++- docs/linting/MONOREPO.md | 82 ------- docs/linting/README.md | 223 ------------------ docs/linting/TROUBLESHOOTING.md | 7 +- docs/linting/TYPED_LINTING.md | 21 +- docs/linting/{ => troubleshooting}/TSLINT.md | 10 +- docs/linting/typed-linting/MONOREPOS.md | 79 +++++++ packages/eslint-plugin/src/configs/README.md | 3 - packages/website/docusaurusConfig.ts | 2 +- packages/website/sidebars/sidebar.base.js | 32 ++- 13 files changed, 235 insertions(+), 346 deletions(-) create mode 100644 _redirects rename docs/linting/{CONFIGS.md => CONFIGURATIONS.md} (62%) delete mode 100644 docs/linting/MONOREPO.md delete mode 100644 docs/linting/README.md rename docs/linting/{ => troubleshooting}/TSLINT.md (63%) create mode 100644 docs/linting/typed-linting/MONOREPOS.md delete mode 100644 packages/eslint-plugin/src/configs/README.md diff --git a/_redirects b/_redirects new file mode 100644 index 000000000000..1b61a020ea0e --- /dev/null +++ b/_redirects @@ -0,0 +1,4 @@ +/docs/linting /docs +/docs/linting/type-linting /docs/linting/typed-linting +/docs/linting/monorepo /docs/linting/typed-linting/monorepos +/docs/linting/tslint /docs/linting/troubleshooting/tslint diff --git a/docs/README.md b/docs/README.md index dfac81e925a2..ade6e2fb073f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,13 +1,85 @@ --- +id: getting-started title: Getting Started -sidebar_label: Getting Started slug: / --- -These docs will give you a quick overview of the project and all of its pieces, as well as provide guides to help you get set up. +## Quickstart -The docs are broken down into the following categories: +These steps will get you running ESLint with our recommended rules on your TypeScript code as quickly as possible. -- [I want to lint my TypeScript codebase.](./linting/README.md) +### Step 1: Installation -- [I want to develop an ESLint plugin in TypeScript.](./development/CUSTOM_RULES.md) +First, install the required packages for [ESLint](https://eslint.io), [TypeScript](https://typescriptlang.org), and this plugin: + +```bash npm2yarn +npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint typescript +``` + +### Step 2: Configuration + +Next, create a `.eslintrc.cjs` config file in the root of your project, and populate it with the following: + + +```js title=".eslintrc.cjs" +module.exports = { + extends: [ + 'eslint:recommended', + 'plugin:@typescript-eslint/recommended', + ], + parser: '@typescript-eslint/parser', + plugins: [ + '@typescript-eslint', + ], + root: true, +}; +``` + +:::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 + +Open a terminal to the root of your project and run the following command: + + + + +```bash +npx eslint . +``` + + + + +```bash +yarn eslint . +``` + + + + +ESLint will lint all TypeScript compatible files within the current folder, and will output the results to your terminal. + +## Details + +- 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). + +### Configuration Values + +- `parser: '@typescript-eslint/parser'` tells ESLint to use the [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser) package you installed to parse your source files. + - This is required, or else ESLint will throw errors as it tries to parse TypeScript code as if it were regular JavaScript. +- `plugins: ['@typescript-eslint']` tells ESLint to load the [`@typescript-eslint/eslint-plugin`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin)) package as a plugin. + - This allows you to use typescript-eslint's rules within your codebase. +- `extends: [ ... ]` tells ESLint that your config extends the given configurations. + - `eslint:recommended` is ESLint's inbuilt "recommended" config - it turns on a small, sensible set of rules which lint for well-known best-practices. + - `plugin:@typescript-eslint/recommended` is our "recommended" config - it's just like `eslint:recommended`, except it only turns on rules from our TypeScript-specific plugin. + +## 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.md '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.md). diff --git a/docs/development/architecture/PACKAGES.md b/docs/development/architecture/PACKAGES.md index 461cc0218120..f798e35b2e47 100644 --- a/docs/development/architecture/PACKAGES.md +++ b/docs/development/architecture/PACKAGES.md @@ -66,7 +66,7 @@ Any custom rules you write generally will be as well. [`@typescript-eslint/eslint-plugin-tslint`] is a separate ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. :::caution -**TSLint is deprecated.** It is in your best interest to migrate off it entirely. See [Linting > TSLint](../../linting/TSLINT.md). +**TSLint is deprecated.** It is in your best interest to migrate off it. See [Linting > Troubleshooting & FAQs > What About TSLint?](../../linting/troubleshooting/TSLINT.md). ::: [`@typescript-eslint/eslint-plugin-tslint`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin-tslint diff --git a/docs/linting/CONFIGS.md b/docs/linting/CONFIGURATIONS.md similarity index 62% rename from docs/linting/CONFIGS.md rename to docs/linting/CONFIGURATIONS.md index 659064c69017..4931c5fd5873 100644 --- a/docs/linting/CONFIGS.md +++ b/docs/linting/CONFIGURATIONS.md @@ -1,9 +1,10 @@ --- id: configs -sidebar_label: Configurations title: Configurations --- +[ESLint shareable configurations](https://eslint.org/docs/latest/developer-guide/shareable-configs) exist to provide a comprehensive base config for you, with the intention that you add the config and it gives you an opinionated setup. + ## Built-In Configurations `@typescript-eslint/eslint-plugin` includes built-in configurations you can extend from to pull in the recommended starting rules. @@ -11,6 +12,10 @@ title: Configurations With the exception of `strict`, all configurations are considered "stable". Rule additions and removals are treated as breaking changes and will only be done in major version bumps. +:::note +We recommend most packages extend from [`recommended-requiring-type-checking`](#recommended-requiring-type-checking) (which requires [typed linting](./TYPED_LINTING.md)). +::: + ### `eslint-recommended` This ruleset is meant to be used after extending `eslint:recommended`. @@ -89,4 +94,29 @@ See [ESLint's Configuring Rules docs](https://eslint.org/docs/user-guide/configu ### Suggesting Configuration Changes -If you feel strongly that a specific rule should (or should not) be one of these configurations, please feel free to [file an issue](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose) 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. + +## Prettier + +If you use [`prettier`](https://www.npmjs.com/package/prettier), there is also a helpful config to help ensure ESLint doesn't report on formatting issues that prettier will fix: [`eslint-config-prettier`](https://www.npmjs.com/package/eslint-config-prettier). + +Using this config by adding it to the end of your `extends`: + +```js title=".eslintrc.js" +module.exports = { + root: true, + parser: '@typescript-eslint/parser', + plugins: ['@typescript-eslint'], + extends: [ + 'eslint:recommended', + 'plugin:@typescript-eslint/recommended', + // Add this line + 'prettier', + ], +}; +``` + +:::warning +**We strongly recommend you use Prettier or an equivalent**, not ESLint formatting rules. +See [this issue](https://github.com/typescript-eslint/typescript-eslint/issues/4907 'Issue: Docs: Add our opinion on delegating stylistic issues to a tool such as Prettier #4907') for more information. +::: diff --git a/docs/linting/MONOREPO.md b/docs/linting/MONOREPO.md deleted file mode 100644 index 4ec2df161362..000000000000 --- a/docs/linting/MONOREPO.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -id: monorepo -title: Monorepo Configuration -sidebar_label: Monorepo Configuration ---- - -If you're using a monorepo, these docs will help you figure out how to setup typed linting. -If you don't want to use typed linting, then you can stop here - you don't need to do anything special. - -The first question to answer is how are your `tsconfig.json` setup? You should have one of two setups: - -1. One `tsconfig.json` per package (and an optional one in the root) -2. One root `tsconfig.json` - -## One `tsconfig.json` per package (and an optional one in the root) - -Earlier in our docs on [typed linting](./TYPED_LINTING.md), we showed you how to setup a config for typed linting using the `parserOptions.project` option. This option accepts an array of relative paths, allowing you to specify each and every `tsconfig.json` in your monorepo. For those of you with too many packages, you can also supply a [glob path](https://github.com/isaacs/node-glob/blob/f5a57d3d6e19b324522a3fa5bdd5075fd1aa79d1/README.md#glob-primer). - -For example, this is how we specify all of our `tsconfig.json` within this repo. - -```js title=".eslintrc.js" -module.exports = { - root: true, - parser: '@typescript-eslint/parser', - parserOptions: { - tsconfigRootDir: __dirname, - // Remove this line - project: ['./tsconfig.json'], - // Add this line - project: ['./tsconfig.eslint.json', './packages/*/tsconfig.json'], - }, - plugins: ['@typescript-eslint'], - extends: [ - 'eslint:recommended', - 'plugin:@typescript-eslint/recommended', - 'plugin:@typescript-eslint/recommended-requiring-type-checking', - ], -}; -``` - -If you're looking for an example of what the `.eslintrc.js`, and referenced `tsconfig.json` might look like in a real example, look no further than this very repo. We're a multi-package monorepo that uses one `tsconfig.json` per package, that also uses typed linting. - -### 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. We are in the process of investigating solutions with the help of the TypeScript team. - -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: - -- Switching to one root `tsconfig.eslint.json` (see below) -- Using a shell script to only lint one package at a time, using your existing config above. - -## One root `tsconfig.json` - -If you've only got one, you should inspect the `include` paths. If it doesn't include all of your files, then we won't be able to lint them. In this instance, you have two options: add them in to the `include`, or create a new config. - -The former doesn't always work for everyone if they've got a complex build, as adding more paths (like test paths) to `include` could break the build. -In those cases we suggest creating a new config called `tsconfig.eslint.json`, that looks something like this: - -```jsonc title="tsconfig.eslint.json" -{ - // extend your base config to share compilerOptions, etc - "extends": "./tsconfig.json", - "compilerOptions": { - // ensure that nobody can accidentally use this config for a build - "noEmit": true - }, - "include": [ - // whatever paths you intend to lint - "src", - "test", - "tools" - ] -} -``` - -Ensure you update your `.eslintrc.js` to point at this new config file. - -## Troubleshooting - -If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](./TROUBLESHOOTING.md). diff --git a/docs/linting/README.md b/docs/linting/README.md deleted file mode 100644 index 23f0a2b1981a..000000000000 --- a/docs/linting/README.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -id: linting -title: Linting your TypeScript Codebase -sidebar_label: Linting your TypeScript Codebase ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -Whether you're adding linting to a new TypeScript codebase, adding TypeScript to an old codebase, or migrating from the deprecated [TSLint](https://www.npmjs.com/package/tslint), the steps aren't a whole lot different. - -## Installation - -First step is to make sure you've got the required packages installed: - -```bash npm2yarn -npm install --save-dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin -``` - -## Configuration - -Next, create a `.eslintrc.cjs` config file in the root of your project, and populate it with the following: - - -```js title=".eslintrc.cjs" -module.exports = { - root: true, - parser: '@typescript-eslint/parser', - plugins: [ - '@typescript-eslint', - ], - extends: [ - 'eslint:recommended', - 'plugin:@typescript-eslint/recommended', - ], -}; -``` - -This is about the smallest config file we recommend. There's a lot more you can add to this as you further onboard, but this will be enough to get you started. - -:::info - -The `.cjs` extension will explicitly set the file to a [CommonJS module](https://nodejs.org/dist/latest-v18.x/docs/api/modules.html), in case your project has `"type": "module"` in its package.json. - -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. - -::: - -### Details - -Explaining the important bits: - -- `parser: '@typescript-eslint/parser'` tells ESLint to use the parser package you installed ([`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser)). - - This allows ESLint to understand TypeScript syntax. - - This is required, or else ESLint will throw errors as it tries to parse TypeScript code as if it were regular JavaScript. -- `plugins: ['@typescript-eslint']` tells ESLint to load the plugin package you installed ([`@typescript-eslint/eslint-plugin`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin)). - - This allows you to use the rules within your codebase. -- `extends: [ ... ]` tells ESLint that your config extends the given configurations. - - `eslint:recommended` is ESLint's inbuilt "recommended" config - it turns on a small, sensible set of rules which lint for well-known best-practices. - - `plugin:@typescript-eslint/recommended` is our "recommended" config - it's just like `eslint:recommended`, except it only turns on rules from our TypeScript-specific plugin. - -### Ignoring unnecessary files - -Next, create a `.eslintignore` file in the root of your project. -This file will tell ESLint which files and folders it should never lint. - -Add the following lines to the file: - -```ignore title=".eslintignore" -# don't lint build output (make sure it's set to your correct build folder name) -dist -``` - -### Further Configuration Documentation - -- 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 us in [our plugin documentation](https://typescript-eslint.io/rules/). - -## Running ESLint - -With that configured, open a terminal to the root of your project, and run the following command: - - - - -```bash -npx eslint . -``` - - - - -```bash -yarn eslint . -``` - - - - -That's it - ESLint will lint all TypeScript compatible files within the current folder, and will output the results to your terminal. - -You are also recommended to add an npm script in your package.json, so you don't have to repeat the same command every time you run ESLint. - -```json title="package.json" -{ - "scripts": { - "lint": "eslint ." - } -} -``` - -This way, you can invoke the `lint` script directly: - -```bash npm2yarn -npm run lint -``` - -:::note -If you use non-standard file extensions, you will need to explicitly tell ESLint to lint those extensions using the [`--ext` flag](https://eslint.org/docs/user-guide/command-line-interface#--ext) -::: - -You can also get results in realtime inside most IDEs via a plugin - search your IDE's extension store. - -## Next Steps - -With that configured you can now start to delve into the wide and extensive ESLint ecosystem of plugins and configs. - -### Type-Aware Rules - -We have a lot of awesome rules which utilize the power of TypeScript's type information. They require a little bit of extra setup beyond this first step, [so visit the next page to see how to set this up.](./TYPED_LINTING.md) - -### Prettier - -If you use [`prettier`](https://www.npmjs.com/package/prettier), there is also a helpful config to help ensure ESLint doesn't report on formatting issues that prettier will fix: [`eslint-config-prettier`](https://www.npmjs.com/package/eslint-config-prettier). - -Using this config by adding it to the end of your `extends`: - -```js title=".eslintrc.js" -module.exports = { - root: true, - parser: '@typescript-eslint/parser', - plugins: ['@typescript-eslint'], - extends: [ - 'eslint:recommended', - 'plugin:@typescript-eslint/recommended', - // Add this line - 'prettier', - ], -}; -``` - -### Community Configs - -Configurations exist solely to provide a comprehensive base config for you, with the intention that you add the config and it gives you an opinionated setup. -Many configuration packages exist in the ESLint ecosystem. -A few popular all-in-one configs are: - -- Airbnb's ESLint config: [`eslint-config-airbnb-typescript`](https://www.npmjs.com/package/eslint-config-airbnb-typescript). -- Standard: [`eslint-config-standard-with-typescript`](https://www.npmjs.com/package/eslint-config-standard-with-typescript). - -To use one of these complete config packages, you would replace the `extends` with the package name. -For example: - -```js title=".eslintrc.js" -module.exports = { - root: true, - parser: '@typescript-eslint/parser', - plugins: ['@typescript-eslint'], - extends: [ - // Removed lines start - 'eslint:recommended', - 'plugin:@typescript-eslint/recommended', - // Removed lines end - // Add this line - 'airbnb-typescript', - ], -}; -``` - - - -Search ["eslint-config" on npm](https://www.npmjs.com/search?q=eslint-config) for more. - -### Plugins - -ESLint plugins provide additional rules and other functionality on top of ESLint. -Below are just a few examples: - -- ESLint comment restrictions: [`eslint-plugin-eslint-comments`](https://www.npmjs.com/package/eslint-plugin-eslint-comments) -- Import/export conventions : [`eslint-plugin-import`](https://www.npmjs.com/package/eslint-plugin-import) -- Jest testing: [`eslint-plugin-jest`](https://www.npmjs.com/package/eslint-plugin-jest) -- NodeJS best practices: [`eslint-plugin-node`](https://www.npmjs.com/package/eslint-plugin-node) -- React best practices: [`eslint-plugin-react`](https://www.npmjs.com/package/eslint-plugin-react) and [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks) - -Every plugin that is out there includes documentation on the various configurations and rules they offer. -A typical plugin might be used like: - -```js title=".eslintrc.js" -module.exports = { - root: true, - parser: '@typescript-eslint/parser', - plugins: [ - '@typescript-eslint', - // Add this line - 'jest', - ], - extends: [ - 'eslint:recommended', - 'plugin:@typescript-eslint/recommended', - // Add this line - 'plugin:jest/recommended', - ], -}; -``` - - - -Search ["eslint-plugin" on npm](https://www.npmjs.com/search?q=eslint-plugin) for more. - -## Troubleshooting - -If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](./TROUBLESHOOTING.md). diff --git a/docs/linting/TROUBLESHOOTING.md b/docs/linting/TROUBLESHOOTING.md index d9c447b4d0e2..f37f8780a332 100644 --- a/docs/linting/TROUBLESHOOTING.md +++ b/docs/linting/TROUBLESHOOTING.md @@ -1,7 +1,6 @@ --- id: troubleshooting title: Troubleshooting & FAQs -sidebar_label: Troubleshooting & FAQs --- ## I am using a rule from ESLint core, and it doesn't work correctly with TypeScript code @@ -31,12 +30,10 @@ If you don't find an existing extension rule, or the extension rule doesn't work ## I get errors telling me "The file must be included in at least one of the projects provided" -This error means that the file that's being linted is not included in any of the tsconfig files you provided us. +This error means that the file that's being linted is not included in any of the TSConfig files you provided us. This happens when users have test files, config files, or similar that are not included. -There are a couple of solutions to this, depending on what you want to achieve. - -See our docs on [type aware linting](./TYPED_LINTING.md#i-get-errors-telling-me-the-file-must-be-included-in-at-least-one-of-the-projects-provided) for solutions to this. +See our docs on [type aware linting](./TYPED_LINTING.md#i-get-errors-telling-me-the-file-must-be-included-in-at-least-one-of-the-projects-provided) for solutions. ## I use a framework (like Vue) that requires custom file extensions, and I get errors like "You should add `parserOptions.extraFileExtensions` to your config" diff --git a/docs/linting/TYPED_LINTING.md b/docs/linting/TYPED_LINTING.md index ae58028e442b..23ad77202455 100644 --- a/docs/linting/TYPED_LINTING.md +++ b/docs/linting/TYPED_LINTING.md @@ -1,11 +1,9 @@ --- -id: type-linting +id: typed-linting title: Linting with Type Information -sidebar_label: Linting with Type Information --- -Under the hood, the typescript-eslint parser uses TypeScript's compiler APIs to parse the files. This means that we can provide lint rules with access to all of the type information that TypeScript knows about your codebase. - +Some typescript-eslint rules tap utilize the awesome power of TypeScript's type checking APIs to provide much deeper insights into your code. To tap into TypeScript's additional powers, there are two small changes you need to make to your config file: ```js title=".eslintrc.js" @@ -32,22 +30,23 @@ In more detail: - `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory. - `parserOptions.project` tells our parser the relative path where your project's `tsconfig.json` is. - - If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./MONOREPO.md). + - If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/MONOREPOS.md). - `plugin:@typescript-eslint/recommended-requiring-type-checking` is another recommended configuration we provide. This one contains rules that specifically require type information. With that done, run the same lint command you ran before. -You will see new rules reporting errors based on type information! +You may see new rules reporting errors based on type information! ## FAQs ### How is performance? -_But wait_ - I hear you exclaim - _why would you ever not want type-aware rules?_ - -Well (for full disclosure) there is a catch; by including `parserOptions.project` in your config, you are essentially asking TypeScript to do a build of your project before ESLint can do its linting. For small projects this takes a negligible amount of time (a few seconds); for large projects, it can take longer (30s or more). +Typed rules come with a catch. +By including `parserOptions.project` in your config, you incur the performance penalty of asking TypeScript to do a build of your project before ESLint can do its linting. +For small projects this takes a negligible amount of time (a few seconds or less); for large projects, it can take longer. -Most of our users are fine with this, as they think the power of type-aware static analysis is worth it. -Additionally, most users primarily consume lint errors via IDE plugins which, through some caching magic, do not suffer the same penalties. This means that generally they usually only run a complete lint before a push, or via their CI, where the extra time really doesn't matter. +Most of our users do not mind this cost, as it is negligibly small, or failing that worth the power of the more powerful type-aware static analysis rules. +Additionally, most users primarily consume lint errors via IDE plugins which, through caching, do not suffer the same penalties. +This means that generally they usually only run a complete lint before a push, or via their CI, where the extra time often doesn't matter. **We strongly recommend you do use type-aware linting**, but the above information is included so that you can make your own, informed decision. diff --git a/docs/linting/TSLINT.md b/docs/linting/troubleshooting/TSLINT.md similarity index 63% rename from docs/linting/TSLINT.md rename to docs/linting/troubleshooting/TSLINT.md index 0d7954dd3506..e04c65224853 100644 --- a/docs/linting/TSLINT.md +++ b/docs/linting/troubleshooting/TSLINT.md @@ -10,9 +10,10 @@ TSLint was a linter equivalent to ESLint that was written specifically to work d ## Migrating from TSLint to ESLint -If you are looking for help in migrating from TSLint to ESLint, see [`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 plugin ROADMAP.md`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/ROADMAP.md) for an up to date overview of how TSLint rules compare to the ones in this package. +You can look at [the `@typescript-eslint/eslint-plugin` `ROADMAP.md`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/ROADMAP.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. @@ -27,6 +28,5 @@ TSLint had to reimplement everything from editor extensions to auto-fixing to ru 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. -The TypeScript Team themselves also announced their plans to move the TypeScript codebase from TSLint to `typescript-eslint`, -and they have been big supporters of this project. -More details at https://github.com/microsoft/TypeScript/issues/30553. +The TypeScript team also migrated move 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. diff --git a/docs/linting/typed-linting/MONOREPOS.md b/docs/linting/typed-linting/MONOREPOS.md new file mode 100644 index 000000000000..24ebfc1e0ab7 --- /dev/null +++ b/docs/linting/typed-linting/MONOREPOS.md @@ -0,0 +1,79 @@ +--- +id: monorepos +title: Monorepo Configuration +--- + +If you're using a monorepo, these docs will help you figure out how to setup typed linting. +If you don't want to use typed linting, then you can stop here - you don't need to do anything special. + +Configurations will look different based on which setup you use: + +1. [One root `tsconfig.json`](#one-root-tsconfigjson) +2. [One `tsconfig.json` per package (and an optional one in the root)](#one-tsconfigjson-per-package-and-an-optional-one-in-the-root) + +## One root `tsconfig.json` + +If you only have one `tsconfig.json` file _and_ its `include` paths include all the files you'd like to lint, you can directly use it with typescript-eslint without further configuration. + +If its `include` paths cannot include all files to be linted, we suggest creating a new config called `tsconfig.eslint.json`, that looks something like this: + +```jsonc title="tsconfig.eslint.json" +{ + // extend your base config to share compilerOptions, etc + "extends": "./tsconfig.json", + "compilerOptions": { + // ensure that nobody can accidentally use this config for a build + "noEmit": true + }, + "include": [ + // whatever paths you intend to lint + "src", + "test", + "tools" + ] +} +``` + +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.md) 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). + +```js title=".eslintrc.js" +module.exports = { + extends: [ + 'eslint:recommended', + 'plugin:@typescript-eslint/recommended', + 'plugin:@typescript-eslint/recommended-requiring-type-checking', + ], + parser: '@typescript-eslint/parser', + parserOptions: { + tsconfigRootDir: __dirname, + // Remove this line + project: ['./tsconfig.json'], + // Add this line + project: ['./tsconfig.eslint.json', './packages/*/tsconfig.json'], + }, + plugins: ['@typescript-eslint'], + root: true, +}; +``` + +### 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. + +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: + +- Switching to one root `tsconfig.eslint.json` (see below) +- Using a shell script to only lint one package at a time, using your existing config above. + +## Troubleshooting + +If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](../TROUBLESHOOTING.md). diff --git a/packages/eslint-plugin/src/configs/README.md b/packages/eslint-plugin/src/configs/README.md deleted file mode 100644 index c440d3d61c50..000000000000 --- a/packages/eslint-plugin/src/configs/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Premade Configs - -This page has moved to [docs/linting/CONFIGS.md](../../../../docs/linting/CONFIGS.md). diff --git a/packages/website/docusaurusConfig.ts b/packages/website/docusaurusConfig.ts index ed8d4deaa0cf..70c6032abdaa 100644 --- a/packages/website/docusaurusConfig.ts +++ b/packages/website/docusaurusConfig.ts @@ -169,7 +169,7 @@ const config: Config = { url: 'https://typescript-eslint.io', baseUrl: '/', onBrokenLinks: 'throw', - onBrokenMarkdownLinks: 'warn', // If Markdown link resolution fails, it will result in a broken link anyways + onBrokenMarkdownLinks: 'throw', favicon: 'img/favicon.ico', organizationName: 'typescript-eslint', projectName: 'typescript-eslint', diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index 8fbf27e2dc93..8e896c376ad3 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -1,18 +1,34 @@ module.exports = { docs: [ - 'README', { - type: 'category', - label: 'Linting', collapsed: false, items: [ - 'linting/linting', - 'linting/type-linting', + { + label: 'Linting with Type Information', + items: ['linting/typed-linting/monorepos'], + link: { + id: 'linting/typed-linting', + type: 'doc', + }, + type: 'category', + }, 'linting/configs', - 'linting/monorepo', - 'linting/troubleshooting', - 'linting/tslint', + { + label: 'Troubleshooting & FAQs', + link: { + id: 'linting/troubleshooting', + type: 'doc', + }, + type: 'category', + items: ['linting/troubleshooting/tslint'], + }, ], + link: { + id: 'getting-started', + type: 'doc', + }, + label: 'Getting Started', + type: 'category', }, { type: 'category', From 02c4a29707a2f6d5dcc2ba210b1bad14255c648c Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 25 Jun 2022 12:32:18 -0400 Subject: [PATCH 2/7] Fix: check-spelling; lint-markdown --- .cspell.json | 1 + docs/linting/typed-linting/MONOREPOS.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.cspell.json b/.cspell.json index 4691cd152db3..9521ca7c8a54 100644 --- a/.cspell.json +++ b/.cspell.json @@ -88,6 +88,7 @@ "preact", "Premade", "prettier's", + "Quickstart", "recurse", "redeclaration", "redeclarations", diff --git a/docs/linting/typed-linting/MONOREPOS.md b/docs/linting/typed-linting/MONOREPOS.md index 24ebfc1e0ab7..a67d05a9c2c0 100644 --- a/docs/linting/typed-linting/MONOREPOS.md +++ b/docs/linting/typed-linting/MONOREPOS.md @@ -8,8 +8,8 @@ If you don't want to use typed linting, then you can stop here - you don't need Configurations will look different based on which setup you use: -1. [One root `tsconfig.json`](#one-root-tsconfigjson) -2. [One `tsconfig.json` per package (and an optional one in the root)](#one-tsconfigjson-per-package-and-an-optional-one-in-the-root) +1. [One root `tsconfig.json`](#one-root-tsconfigjson) +2. [One `tsconfig.json` per package (and an optional one in the root)](#one-tsconfigjson-per-package-and-an-optional-one-in-the-root) ## One root `tsconfig.json` From 5afafa1d79ee9b414c5f13e9af5bd0fea0cab0a4 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 25 Jun 2022 12:49:49 -0400 Subject: [PATCH 3/7] Fixed remaining typed-linting issues --- docs/linting/CONFIGURATIONS.md | 2 +- packages/eslint-plugin/README.md | 2 +- packages/parser/README.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/linting/CONFIGURATIONS.md b/docs/linting/CONFIGURATIONS.md index 4931c5fd5873..de05a216ff87 100644 --- a/docs/linting/CONFIGURATIONS.md +++ b/docs/linting/CONFIGURATIONS.md @@ -65,7 +65,7 @@ Rules in this configuration are similarly useful to those in `recommended`. :::tip We recommend all TypeScript projects extend from this configuration, with the caveat that rules using type information take longer to run. -See [Linting with Type Information](/docs/linting/type-linting) for more details. +See [Linting with Type Information](/docs/linting/typed-linting) for more details. ::: ### `strict` diff --git a/packages/eslint-plugin/README.md b/packages/eslint-plugin/README.md index 60a769945183..6ae129ec315d 100644 --- a/packages/eslint-plugin/README.md +++ b/packages/eslint-plugin/README.md @@ -85,7 +85,7 @@ Some highly valuable rules require type-checking in order to be implemented corr Pro Tip: For larger codebases you may want to consider splitting our linting into two separate stages: 1. fast feedback rules which operate purely based on syntax (no type-checking), 2. rules which are based on semantics (type-checking). -**[You can read more about linting with type information here](https://typescript-eslint.io/docs/linting/type-linting)** +**[You can read more about linting with type information here](https://typescript-eslint.io/docs/linting/typed-linting)** ## Supported Rules diff --git a/packages/parser/README.md b/packages/parser/README.md index 018935b2ca9f..3488cd5e5052 100644 --- a/packages/parser/README.md +++ b/packages/parser/README.md @@ -256,7 +256,7 @@ Note that if you pass custom programs via `options.programs` this option will no 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](https://typescript-eslint.io/docs/linting/type-linting). 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](https://typescript-eslint.io/docs/linting/typed-linting). In other words, you don't have to specify `parserOptions.project` in this case, making the linting process faster. ## Utilities From 8c8f7505fdb033380c4c12446b36eb88e0048eec Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 25 Jun 2022 16:28:43 -0400 Subject: [PATCH 4/7] chore: add formatting (Prettier) page to the website --- docs/linting/troubleshooting/FORMATTING.md | 36 ++++++++++++++++++++++ packages/website/sidebars/sidebar.base.js | 5 ++- 2 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 docs/linting/troubleshooting/FORMATTING.md diff --git a/docs/linting/troubleshooting/FORMATTING.md b/docs/linting/troubleshooting/FORMATTING.md new file mode 100644 index 000000000000..a0edae063d82 --- /dev/null +++ b/docs/linting/troubleshooting/FORMATTING.md @@ -0,0 +1,36 @@ +--- +id: formatting +title: What About Formatting? +--- + +We strongly recommend you do not use ESLint for formatting. +We strongly recommend you use [Prettier](https://prettier.io), [dprint](https://dprint.dev), or an equivalent. + +## Formatters vs. Linters + +**Formatters** are tools that verify and correct whitespace issues in code, such as spacing and newlines. +Formatters typically run very quickly because they are only concerned with changing whitespace, not code logic or naming. + +**Linters** are tools that verify and correct logical and non-whitespace style issues in code, such as naming consistency and bug detection. +Linters often take seconds or more to run because they apply many logical rules to code. + +### Problems with Using Linters as Formatters + +Linters apply much more work than formatters -- often including potentially multiple rounds of rule fixers. +That generally makes them run orders of magnitude slower. + +Additionally, modern formatters such as Prettier are architected in a way that applies formatting to all code regardless of original formatting. +Linters typically run on a rule-by-rule basis, typically resulting in many edge cases and missed coverage in formatting. + +## ESLint Core and Formatting + +Per [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies#what-are-the-changes): + +> 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. +> Stylistic rules are those related to spacing, conventions, and generally anything that does not highlight an error or a better way to do something. +> +> Update 2021-01-29: We clarified in the README that we will still support newly-added ECMAScript features. + +We support the ESLint team's decision and backing logic to move away from stylistic rules. +With the exception of bug fixes, no new formatting-related pull requests will be accepted into typescript-eslint. diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index 8e896c376ad3..5b16af7f5f91 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -20,7 +20,10 @@ module.exports = { type: 'doc', }, type: 'category', - items: ['linting/troubleshooting/tslint'], + items: [ + 'linting/troubleshooting/formatting', + 'linting/troubleshooting/tslint', + ], }, ], link: { From 79ed79d837fbe248d86237fd847f42334104d407 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 25 Jun 2022 16:30:21 -0400 Subject: [PATCH 5/7] nit: first wording --- docs/linting/troubleshooting/FORMATTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/linting/troubleshooting/FORMATTING.md b/docs/linting/troubleshooting/FORMATTING.md index a0edae063d82..1529cd431fd8 100644 --- a/docs/linting/troubleshooting/FORMATTING.md +++ b/docs/linting/troubleshooting/FORMATTING.md @@ -3,8 +3,8 @@ id: formatting title: What About Formatting? --- -We strongly recommend you do not use ESLint for formatting. -We strongly recommend you use [Prettier](https://prettier.io), [dprint](https://dprint.dev), or an equivalent. +We strongly recommend against using ESLint for formatting. +We strongly recommend using [Prettier](https://prettier.io), [dprint](https://dprint.dev), or an equivalent instead. ## Formatters vs. Linters From a8abe2fbb996aea2e086dd439acc428ad1fcdde0 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 22 Jul 2022 14:05:38 -0400 Subject: [PATCH 6/7] Update docs/linting/troubleshooting/FORMATTING.md --- docs/linting/troubleshooting/FORMATTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/linting/troubleshooting/FORMATTING.md b/docs/linting/troubleshooting/FORMATTING.md index 1529cd431fd8..d39fdd568246 100644 --- a/docs/linting/troubleshooting/FORMATTING.md +++ b/docs/linting/troubleshooting/FORMATTING.md @@ -29,8 +29,6 @@ Per [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2 > 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. > Stylistic rules are those related to spacing, conventions, and generally anything that does not highlight an error or a better way to do something. -> -> Update 2021-01-29: We clarified in the README that we will still support newly-added ECMAScript features. We support the ESLint team's decision and backing logic to move away from stylistic rules. With the exception of bug fixes, no new formatting-related pull requests will be accepted into typescript-eslint. From af17ab27fa4088b083785e8b963dd2ad6e3e8f4d Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 22 Jul 2022 14:50:38 -0400 Subject: [PATCH 7/7] Add dprint to cspell dictionary --- .cspell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.cspell.json b/.cspell.json index f1f863b59523..0c5b1d6c2866 100644 --- a/.cspell.json +++ b/.cspell.json @@ -59,6 +59,7 @@ "declarators", "destructure", "destructured", + "dprint", "errored", "erroring", "ESLint", pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy