From 71349a1f709baa361bd656a7ce4a7d35d857a9a8 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter <57849986+bpmutter@users.noreply.github.com> Date: Thu, 2 Feb 2023 05:48:44 -0500 Subject: [PATCH] docs: Configure a Parser page (#16803) * docs: Configure a Parser page Resolves #16762 * Apply suggestions from code review Co-authored-by: Brandon Mills --------- Co-authored-by: Brandon Mills --- docs/src/use/configure/ignore.md | 2 +- docs/src/use/configure/index.md | 5 +++- docs/src/use/configure/parser.md | 38 +++++++++++++++++++++++++++++++ docs/src/use/configure/plugins.md | 34 ++------------------------- 4 files changed, 45 insertions(+), 34 deletions(-) create mode 100644 docs/src/use/configure/parser.md diff --git a/docs/src/use/configure/ignore.md b/docs/src/use/configure/ignore.md index ac481547895..ffc23428ee0 100644 --- a/docs/src/use/configure/ignore.md +++ b/docs/src/use/configure/ignore.md @@ -4,7 +4,7 @@ eleventyNavigation: key: ignore files parent: configure title: Ignore Files - order: 6 + order: 7 --- diff --git a/docs/src/use/configure/index.md b/docs/src/use/configure/index.md index 05850e9f1d5..44f84aa4291 100644 --- a/docs/src/use/configure/index.md +++ b/docs/src/use/configure/index.md @@ -49,7 +49,10 @@ All of these options give you fine-grained control over how ESLint treats your c * [Configure Plugins](./plugins#configure-plugins) * [Specify a Processor](./plugins#specify-a-processor) -* [Configure Parsers](./plugins#configure-a-parser) + +[**Configure a Parser**](./parser) + +* [Configure a Custom Parser](./parser#configure-a-custom-parser) [**Ignore Files**](ignore) diff --git a/docs/src/use/configure/parser.md b/docs/src/use/configure/parser.md new file mode 100644 index 00000000000..76d94d15fc1 --- /dev/null +++ b/docs/src/use/configure/parser.md @@ -0,0 +1,38 @@ +--- +title: Configure a Parser +eleventyNavigation: + key: configure parser + parent: configure + title: Configure a Parser + order: 6 +--- + +You can use custom parsers to convert JavaScript code into an abstract syntax tree for ESLint to evaluate. You might want to add a custom parser if your code isn't compatible with ESLint's default parser, Espree. + +## Configure a Custom Parser + +By default, ESLint uses [Espree](https://github.com/eslint/espree) as its parser. You can optionally specify that a different parser should be used in your configuration file if the parser meets the following requirements: + +1. It must be a Node module loadable from the config file where the parser is used. Usually, this means you should install the parser package separately using npm. +1. It must conform to the [parser interface](../../extend/custom-parsers). + +Note that even with these compatibilities, there are no guarantees that an external parser works correctly with ESLint. ESLint does not fix bugs related to incompatibilities with other parsers. + +To indicate the npm module to use as your parser, specify it using the `parser` option in your `.eslintrc` file. For example, the following specifies to use Esprima instead of Espree: + +```json +{ + "parser": "esprima", + "rules": { + "semi": "error" + } +} +``` + +The following parsers are compatible with ESLint: + +* [Esprima](https://www.npmjs.com/package/esprima) +* [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser) - A wrapper around the [Babel](https://babeljs.io) parser that makes it compatible with ESLint. +* [@typescript-eslint/parser](https://www.npmjs.com/package/@typescript-eslint/parser) - A parser that converts TypeScript into an ESTree-compatible form so it can be used in ESLint. + +Note that when using a custom parser, the `parserOptions` configuration property is still required for ESLint to work properly with features not in ECMAScript 5 by default. Parsers are all passed `parserOptions` and may or may not use them to determine which features to enable. diff --git a/docs/src/use/configure/plugins.md b/docs/src/use/configure/plugins.md index 2c4706ff476..3026592c418 100644 --- a/docs/src/use/configure/plugins.md +++ b/docs/src/use/configure/plugins.md @@ -1,9 +1,9 @@ --- -title: Configure Plugins & Parsers +title: Configure Plugins eleventyNavigation: key: configure plugins parent: configure - title: Configure Plugins & Parsers + title: Configure Plugins order: 5 --- @@ -15,8 +15,6 @@ You can extend ESLint with plugins in a variety of different ways. Plugins can i * Custom environments. * Custom processors to extract JavaScript code from other kinds of files or preprocess code before linting. -You can also use custom parsers to convert JavaScript code into an abstract syntax tree for ESLint to evaluate. You might want to add a custom parser if your code isn't compatible with ESLint's default parser, Espree. - ## Configure Plugins ESLint supports the use of third-party plugins. Before using a plugin, you have to install it using npm. @@ -161,31 +159,3 @@ Processors may make named code blocks such as `0.js` and `1.js`. ESLint handles ``` ESLint checks the file path of named code blocks then ignores those if any `overrides` entry didn't match the file path. Be sure to add an `overrides` entry if you want to lint named code blocks other than `*.js`. - -## Configure a Parser - -By default, ESLint uses [Espree](https://github.com/eslint/espree) as its parser. You can optionally specify that a different parser should be used in your configuration file if the parser meets the following requirements: - -1. It must be a Node module loadable from the config file where the parser is used. Usually, this means you should install the parser package separately using npm. -1. It must conform to the [parser interface](../../extend/custom-parsers). - -Note that even with these compatibilities, there are no guarantees that an external parser works correctly with ESLint. ESLint does not fix bugs related to incompatibilities with other parsers. - -To indicate the npm module to use as your parser, specify it using the `parser` option in your `.eslintrc` file. For example, the following specifies to use Esprima instead of Espree: - -```json -{ - "parser": "esprima", - "rules": { - "semi": "error" - } -} -``` - -The following parsers are compatible with ESLint: - -* [Esprima](https://www.npmjs.com/package/esprima) -* [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser) - A wrapper around the [Babel](https://babeljs.io) parser that makes it compatible with ESLint. -* [@typescript-eslint/parser](https://www.npmjs.com/package/@typescript-eslint/parser) - A parser that converts TypeScript into an ESTree-compatible form so it can be used in ESLint. - -Note that when using a custom parser, the `parserOptions` configuration property is still required for ESLint to work properly with features not in ECMAScript 5 by default. Parsers are all passed `parserOptions` and may or may not use them to determine which features to enable.