From 5bdaae205c3a0089ea338b382df59e21d5b06436 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter <57849986+bpmutter@users.noreply.github.com> Date: Sun, 12 Feb 2023 14:12:16 -0500 Subject: [PATCH] docs: Ways to Extend ESLint page (#16861) * docs: Ways to Extend page * ways to extend * finish draft of page * copy edit * Remove name .eslintrc * custom parser link sentence * Apply suggestions from code review Co-authored-by: Amaresh S M * custom formatters section and link fix * change order * Apply suggestions from code review Co-authored-by: Milos Djermanovic Co-authored-by: Nitin Kumar --------- Co-authored-by: Amaresh S M Co-authored-by: Milos Djermanovic Co-authored-by: Nitin Kumar --- docs/src/extend/custom-formatters.md | 2 +- docs/src/extend/custom-parsers.md | 2 +- docs/src/extend/custom-rules.md | 2 +- docs/src/extend/index.md | 4 ++ docs/src/extend/plugins.md | 2 +- docs/src/extend/ways-to-extend.md | 60 ++++++++++++++++++++++++++++ 6 files changed, 68 insertions(+), 4 deletions(-) create mode 100644 docs/src/extend/ways-to-extend.md diff --git a/docs/src/extend/custom-formatters.md b/docs/src/extend/custom-formatters.md index 29376d2a850..4506f0f35fd 100644 --- a/docs/src/extend/custom-formatters.md +++ b/docs/src/extend/custom-formatters.md @@ -4,7 +4,7 @@ eleventyNavigation: key: custom formatters parent: extend eslint title: Custom Formatters - order: 3 + order: 4 --- diff --git a/docs/src/extend/custom-parsers.md b/docs/src/extend/custom-parsers.md index e49c24c98a9..a341da5088a 100644 --- a/docs/src/extend/custom-parsers.md +++ b/docs/src/extend/custom-parsers.md @@ -4,7 +4,7 @@ eleventyNavigation: key: custom parsers parent: extend eslint title: Custom Parsers - order: 4 + order: 5 --- diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 62e5336df49..cbb9be2d175 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -4,7 +4,7 @@ eleventyNavigation: key: custom rules parent: extend eslint title: Custom Rules - order: 2 + order: 3 --- diff --git a/docs/src/extend/index.md b/docs/src/extend/index.md index 926f70e3913..9f623a6119d 100644 --- a/docs/src/extend/index.md +++ b/docs/src/extend/index.md @@ -17,6 +17,10 @@ In order to extend ESLint, it's recommended that: If that sounds like you, then continue reading to get started. +## [Ways to Extend ESLint](ways-to-extend) + +This page summarizes the various ways that you can extend ESLint and how these extensions all fit together. + ## [Create Plugins](plugins) You've developed custom rules for ESLint and you want to share them with the community. You can publish an ESLint plugin on npm. diff --git a/docs/src/extend/plugins.md b/docs/src/extend/plugins.md index 970581ae4f2..6c063d599e0 100644 --- a/docs/src/extend/plugins.md +++ b/docs/src/extend/plugins.md @@ -4,7 +4,7 @@ eleventyNavigation: key: create plugins parent: extend eslint title: Create Plugins - order: 1 + order: 2 --- diff --git a/docs/src/extend/ways-to-extend.md b/docs/src/extend/ways-to-extend.md new file mode 100644 index 00000000000..0432492b60e --- /dev/null +++ b/docs/src/extend/ways-to-extend.md @@ -0,0 +1,60 @@ +--- +title: Ways to Extend ESLint +eleventyNavigation: + key: ways to extend + parent: extend eslint + title: Ways to Extend ESLint + order: 1 +--- + +ESLint is highly pluggable and configurable. There are a variety of ways that you can extend ESLint's functionality. + +This page explains the ways to extend ESLint, and how these extensions all fit together. + +## Plugins + +Plugins let you add your own ESLint custom rules and custom processors to a project. You can publish a plugin as an npm module. + +Plugins are useful because your project may require some ESLint configuration that isn't included in the core `eslint` package. For example, if you're using a frontend JavaScript library like React or framework like Vue, these tools have some features that require custom rules outside the scope of the ESLint core rules. + +Often a plugin is paired with a configuration for ESLint that applies a set of features from the plugin to a project. You can include configurations in a plugin as well. + +For example, [`eslint-plugin-react`](https://www.npmjs.com/package/eslint-plugin-react) is an ESLint plugin that includes rules specifically for React projects. The rules include things like enforcing consistent usage of React component lifecycle methods and requiring the use of key props when rendering dynamic lists. + +To learn more about creating the extensions you can include in a plugin, refer to the following documentation: + +* [Custom Rules](custom-rules) +* [Custom Processors](custom-processors) +* [Configs in Plugins](plugins#configs-in-plugins) + +To learn more about bundling these extensions into a plugin, refer to [Plugins](plugins). + +## Shareable Configs + +ESLint shareable configs are pre-defined configurations for ESLint that you can use in your projects. They bundle rules and other configuration together in an npm package. Anything that you can put in a configuration file can be put in a shareable config. + +You can either publish a shareable config independently or as part of a plugin. + +For example, a popular shareable config is [eslint-config-airbnb](https://www.npmjs.com/package/eslint-config-airbnb), which contains a variety of rules in addition to some [parser options](../use/configure/language-options#specifying-parser-options). This is a set of rules for ESLint that is designed to match the style guide used by the [Airbnb JavaScript style guide](https://github.com/airbnb/javascript). By using the `eslint-config-airbnb` shareable config, you can automatically enforce the Airbnb style guide in your project without having to manually configure each rule. + +To learn more about creating a shareable config, refer to [Share Configuration](shareable-configs). + +## Custom Formatters + +Custom formatters take ESLint linting results and output the results in a format that you define. Custom formatters let you display linting results in a format that best fits your needs, whether that's in a specific file format, a certain display style, or a format optimized for a particular tool. You only need to create a custom formatter if the [built-in formatters](../use/formatters/) don't serve your use case. + +For example, the custom formatter [eslint-formatter-gitlab](https://www.npmjs.com/package/eslint-formatter-gitlab) can be used to display ESLint results in GitLab code quality reports. + +To learn more about creating a custom formatter, refer to [Custom Formatters](custom-formatters). + +## Custom Parsers + +ESLint custom parsers are a way to extend ESLint to support the linting of new language features or custom syntax in your code. A parser is responsible for taking your code and transforming it into an abstract syntax tree (AST) that ESLint can then analyze and lint. + +ESLint ships with a built-in JavaScript parser (Espree), but custom parsers allow you to lint other languages or to extend the linting capabilities of the built-in parser. + +For example, the custom parser [@typescript-eslint/parser](https://typescript-eslint.io/architecture/parser/) extends ESLint to lint TypeScript code. + +Custom parsers **cannot** be included in a plugin, unlike the other extension types. + +To learn more about creating a custom parser, refer to [Custom Parsers](custom-parsers).