astro-eslint-parser
Version:
Astro component parser for ESLint
210 lines (153 loc) • 7.9 kB
Markdown
# astro-eslint-parser
[Astro] component parser for [ESLint].
You can check it on [Online DEMO](https://ota-meshi.github.io/astro-eslint-parser/playground).
[](https://github.com/sponsors/ota-meshi)
[](https://www.npmjs.com/package/astro-eslint-parser)
[](https://www.npmjs.com/package/astro-eslint-parser)
[](http://www.npmtrends.com/astro-eslint-parser)
[](http://www.npmtrends.com/astro-eslint-parser)
[](http://www.npmtrends.com/astro-eslint-parser)
[](http://www.npmtrends.com/astro-eslint-parser)
[](http://www.npmtrends.com/astro-eslint-parser)
[](https://github.com/ota-meshi/astro-eslint-parser/actions?query=workflow%3ACI)
[](https://coveralls.io/github/ota-meshi/astro-eslint-parser?branch=main)
This parser is in the ***experimental stages*** of development.
At least it works fine with a [withastro/docs](https://github.com/withastro/docs) repository.
[@astrojs/compiler]: https://github.com/withastro/compiler
## :checkered_flag: Motivation
This parser allows us to lint the script of `.astro` files.
> Note that this parser alone will not lint the scripts inside the `<script>` tag. Use [eslint-plugin-astro] to lint the script inside the `<script>` tag as well.
### ESLint Plugins Using astro-eslint-parser
#### [eslint-plugin-astro]
ESLint plugin for Astro component.
## 💿 Installation
```bash
npm install --save-dev eslint astro-eslint-parser
```
## 📖 Usage
**First, we recommend using [eslint-plugin-astro] rather than just the parser.**
The following usage it are for introducing only the parser. This is not useful for most people. It can be useful if you create your own plugin.
1. Write `overrides[*].parser` option into your `.eslintrc.*` file.
```json
{
"extends": "eslint:recommended",
"overrides": [
{
"files": ["*.astro"],
"parser": "astro-eslint-parser"
}
]
}
```
2. If you have specified the extension in the CLI, add `.astro` as well.
```console
$ eslint "src/**/*.{js,astro}"
# or
$ eslint src --ext .js,.astro
```
The commit diff [here](https://github.com/withastro/astro.build/compare/main...ota-meshi:eslint) is an example of introducing this parser to the `astro.build` repository.
## 🔧 Options
`parserOptions` has the same properties as what [espree](https://github.com/eslint/espree#usage), the default parser of ESLint, is supporting.
For example:
```json
{
"parser": "astro-eslint-parser",
"parserOptions": {
"sourceType": "module",
"ecmaVersion": 2021,
"ecmaFeatures": {
"globalReturn": false,
"impliedStrict": false,
"jsx": false
}
}
}
```
### parserOptions.parser
You can use `parserOptions.parser` property to specify a custom parser to parse scripts.
Other properties than parser would be given to the specified parser.
For example:
```json
{
"parser": "astro-eslint-parser",
"parserOptions": {
"parser": "@typescript-eslint/parser"
}
}
```
For example, if you are using the `"@typescript-eslint/parser"`, and if you want to use TypeScript in `.astro`, you need to add more `parserOptions` configuration.
```js
module.exports = {
// ...
parser: "@typescript-eslint/parser",
parserOptions: {
// ...
project: "path/to/your/tsconfig.json",
extraFileExtensions: [".astro"], // This is a required setting in `@typescript-eslint/parser` v5.
},
overrides: [
{
files: ["*.astro"],
parser: "astro-eslint-parser",
// Parse the script in `.astro` as TypeScript by adding the following configuration.
parserOptions: {
parser: "@typescript-eslint/parser",
},
},
// ...
],
// ...
}
```
When using JavaScript configuration (`.eslintrc.js`), you can also give the parser object directly.
```js
const tsParser = require("@typescript-eslint/parser")
module.exports = {
parser: "astro-eslint-parser",
parserOptions: {
parser: tsParser,
},
}
```
## :computer: Editor Integrations
### Visual Studio Code
Use the [dbaeumer.vscode-eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) extension that Microsoft provides officially.
You have to configure the `eslint.validate` option of the extension to check `.astro` files, because the extension targets only `*.js` or `*.jsx` files by default.
Example **.vscode/settings.json**:
```json
{
"eslint.validate": [
"javascript",
"javascriptreact",
"astro"
]
}
```
## :handshake: Compatibility With Existing ESLint Rules
Most of the rules in the ESLint core work for the script part, but some rules are incompatible.
This parser will generate a JSX compatible AST for most of the HTML part of the Astro component. Therefore, some rules of [eslint-plugin-react] may work.
For example, the [react/jsx-no-target-blank] rule works fine.
[eslint-plugin-react]: https://github.com/jsx-eslint/eslint-plugin-react/
[react/jsx-no-target-blank]: https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-target-blank.md
## :ghost: Limitations
If this parser is used with `@typescript-eslint/parser` and `parserOptions.project` is set, it will temporarily create a `.tsx` file to parse the `.astro` file.
This parser works by converting the `.astro` file to JSX and letting the JavaScript parser parse it.
Since `@typescript-eslint/parser` can only parse files with the extension `.tsx` as JSX, it is necessary to temporarily create a `.tsx` file. Temporarily created files will try to be deleted after parses, but if the parsing takes a long time, the files may be visible to you.
See also [`@typescript-eslint/parser` readme](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsecmafeaturesjsx).
## :hammer_and_wrench: Usage for Custom Rules / Plugins
<!-- - [AST.md](./docs/AST.md) is AST specification. You can check it on the [Online DEMO](https://ota-meshi.github.io/astro-eslint-parser/). -->
- TBA
- You can check the AST in the [Online DEMO](https://ota-meshi.github.io/astro-eslint-parser/). However, AST is subject to major changes in the future.
- I have already [implemented some rules] in the [eslint-plugin-astro]. The source code for these rules will be helpful to you.
## :beers: Contributing
Welcome contributing!
Please use GitHub's Issues/PRs.
## :heart: Supporting
If you are willing to see that this package continues to be maintained, please consider sponsoring me.
[](https://github.com/sponsors/ota-meshi)
## :lock: License
See the [LICENSE](LICENSE) file for license rights and limitations (MIT).
[Astro]: https://astro.build/
[ESLint]: https://eslint.org/
[eslint-plugin-astro]: https://ota-meshi.github.io/eslint-plugin-astro/
[implemented some rules]: https://ota-meshi.github.io/eslint-plugin-astro/rules/