eslint-plugin-astro
Version:
ESLint plugin for Astro component
422 lines (306 loc) • 23.6 kB
Markdown
# Introduction
`eslint-plugin-astro` is [ESLint] plugin for [Astro components].
You can check on the [Online DEMO](https://ota-meshi.github.io/eslint-plugin-astro/playground/).
[](https://github.com/sponsors/ota-meshi)
[](https://www.npmjs.com/package/eslint-plugin-astro)
[](https://www.npmjs.com/package/eslint-plugin-astro)
[](http://www.npmtrends.com/eslint-plugin-astro)
[](http://www.npmtrends.com/eslint-plugin-astro)
[](http://www.npmtrends.com/eslint-plugin-astro)
[](http://www.npmtrends.com/eslint-plugin-astro)
[](http://www.npmtrends.com/eslint-plugin-astro)
[](https://github.com/ota-meshi/eslint-plugin-astro/actions?query=workflow%3ACI)
[](https://coveralls.io/github/ota-meshi/eslint-plugin-astro?branch=main)
This plugin is in the **_experimental stages_** of development.
At least it works fine with a [withastro/docs](https://github.com/withastro/docs) repository.
## 📛 What is this plugin?
[ESLint] plugin for [Astro components].
- Linting Astro components using ESLint.
- Find problems with Astro components.
- Apply a consistent code style to Astro components.
- Linting targets include [Frontmatter], [HTML Template], [JSX-like Expressions], [Client-Side Scripts], [Directives], and more.
- Check code in real time with the ESLint editor integrations.
[frontmatter]: https://docs.astro.build/en/core-concepts/astro-components/#the-component-script
[html template]: https://docs.astro.build/en/core-concepts/astro-components/#the-component-template
[JSX-like Expressions]: https://docs.astro.build/en/core-concepts/astro-syntax/#jsx-like-expressions
[client-side scripts]: https://docs.astro.build/en/guides/client-side-scripts/
[directives]: https://docs.astro.build/en/reference/directives-reference/
<!--DOCS_IGNORE_START-->
## 📖 Documentation
See [documents](https://ota-meshi.github.io/eslint-plugin-astro/).
<!--INSTALL_GUIDE_START-->
## 💿 Installation
```bash
npm install --save-dev eslint eslint-plugin-astro
```
If you write TypeScript in Astro components, you also need to install either `typescript-eslint` or `@typescript-eslint/parser`:
```bash
npm install --save-dev typescript-eslint
# or
npm install --save-dev @typescript-eslint/parser
```
If you want to use the rules for checking accessibility (A11Y), you also need to install [eslint-plugin-jsx-a11y] additionally:
(It is used internally in the rules for A11Y.)
```bash
npm install --save-dev eslint-plugin-jsx-a11y
```
[eslint-plugin-jsx-a11y]: https://github.com/jsx-eslint/eslint-plugin-jsx-a11y
> **Requirements**
>
> - ESLint v10.0.0 and above
> - Node.js v22.22.3, v24.16.0, v26.3.0 and above
<!--INSTALL_GUIDE_END-->
<!--DOCS_IGNORE_END-->
## 📖 Usage
<!--USAGE_SECTION_START-->
<!--USAGE_GUIDE_START-->
### Configuration
#### Flat Config \(`eslint.config.js`\)
This package is ESM-only. Use `eslint.config.mjs`, or use `eslint.config.js` in a project with `"type": "module"`. See also: [https://eslint.org/docs/latest/use/configure/configuration-files](https://eslint.org/docs/latest/use/configure/configuration-files).
Example **eslint.config.js**:
```js
import eslintPluginAstro from "eslint-plugin-astro"
export default [
// add more generic rule sets here, such as:
// js.configs.recommended,
...eslintPluginAstro.configs.recommended,
{
rules: {
// override/add rules settings here, such as:
// "astro/no-set-html-directive": "error"
},
},
]
```
This plugin provides configs:
- `base` ... Minimal configuration to enable correct Astro component linting.
- `recommended` ... Above, plus rules to prevent errors or unintended behavior.
- `all` ... Configuration enables all astro rules. It's meant for testing, not for production use because it changes with every minor and major version of the plugin. Use it at your own risk.
- Extension of sharable configuration provided by [eslint-plugin-jsx-a11y]. You need to install [eslint-plugin-jsx-a11y] to use it.
- `jsx-a11y-recommended` ... Similar to the [`jsx-a11y` recommended configuration](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y#rule-strictness-in-different-modes), but with the rules extended for Astro components enabled.
- `jsx-a11y-strict` ... Similar to the [`jsx-a11y` strict configuration](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y#rule-strictness-in-different-modes), but with the rules extended for Astro components enabled.
See [the rule list](https://ota-meshi.github.io/eslint-plugin-astro/rules/) to get the `rules` that this plugin provides.
The pull request diff [here](https://github.com/withastro/docs/pull/710/files) is an example of introducing `eslint-plugin-astro` to the [withastro/docs](https://github.com/withastro/docs) repository.
#### Parser Configuration
See [https://github.com/ota-meshi/astro-eslint-parser#readme](https://github.com/ota-meshi/astro-eslint-parser#readme).
#### Using `eslint-plugin-import`
When using [`eslint-plugin-import`](https://github.com/import-js/eslint-plugin-import), configure it to parse Astro files and recognize Astro's virtual modules. After applying the plugin's recommended configuration, add the following config object:
```json
{
"settings": {
"import/core-modules": ["astro:content", "astro:transitions"],
"import/parsers": {
"astro-eslint-parser": [".astro"],
"espree": [".js", ".mjs", ".cjs"],
"@typescript-eslint/parser": [".ts", ".tsx"]
}
}
}
```
Add any other virtual `astro:*` modules that your project imports to `import/core-modules`. Only include parser entries for file types and parsers that your project uses.
### Resolving Error in JSX: Unsafe return of an `any` typed value
Astro supports JSX from multiple frameworks such as **React**, **Preact**, and **Solid.js** by defining JSX Elements as `HTMLElement | any;`. When a framework with a JSX type definition is not present in your project this **any** can cause the ESLint error `@typescript-eslint/no-unsafe-return`.
This can be resolved by overriding the astroHTML.JSX.Element definition with a `*.d.ts` file such as `jsx.d.ts` in your project root directory:
```typescript
import "astro/astro-jsx";
declare global {
namespace JSX {
// type Element = astroHTML.JSX.Element // We want to use this, but it is defined as any.
type Element = HTMLElement;
}
}
```
Add this `*.d.ts` to your `tsconfig.eslint.json`:
```json
{
"extends": "./tsconfig.json",
"include": [
// ...
"jsx.d.ts"
]
}
```
If you use typed linting for Astro files, point `languageOptions.parserOptions.project` at this config:
```js
import eslintPluginAstro from "eslint-plugin-astro"
export default [
...eslintPluginAstro.configs.recommended,
{
files: ["*.astro", "**/*.astro"],
languageOptions: {
parserOptions: {
// add this line
project: "./tsconfig.eslint.json",
},
},
},
]
```
Alternatively, add the `project` option to an existing Astro config entry:
```js
export default [
// ...
{
files: ["*.astro", "**/*.astro"],
languageOptions: {
parserOptions: {
project: "./tsconfig.eslint.json",
},
},
},
]
```
### Running ESLint from the command line
If you want to run `eslint` from the command line, make sure you include the `.astro` extension using a glob pattern, because ESLint targets only `.js` files by default.
Examples:
```bash
eslint "src/**/*.{js,astro}"
```
## 💻 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", // Enable .astro
"typescript", // Enable .ts
"typescriptreact" // Enable .tsx
]
}
```
### Zed
Zed has built-in support for ESLint. However, you need to configure ESLint to work with Astro files.
Example **.zed/settings.json**:
```json
{
"languages": {
"Astro": {
"language_servers": ["eslint", "..."]
}
}
}
```
<!--USAGE_GUIDE_END-->
<!--USAGE_SECTION_END-->
## ✅ Rules
<!--RULES_SECTION_START-->
The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) automatically fixes problems reported by rules which have a wrench 🔧 below.
The rules with the following star ⭐ are included in the `recommended` config.
> Doesn't the rule you want exist? [Share your idea of that rule with us](https://github.com/ota-meshi/eslint-plugin-astro/issues/new?template=new_rule_request.yml).
<!--RULES_TABLE_START-->
## Possible Errors
These rules relate to possible syntax or logic errors in Astro component code:
| Rule ID | Description | |
|:--------|:------------|:---|
| [astro/missing-client-only-directive-value](https://ota-meshi.github.io/eslint-plugin-astro/rules/missing-client-only-directive-value/) | the client:only directive is missing the correct component's framework value | ⭐ |
| [astro/no-conflict-set-directives](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-conflict-set-directives/) | disallow conflicting set directives and child contents | ⭐ |
| [astro/no-deprecated-astro-canonicalurl](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-deprecated-astro-canonicalurl/) | disallow using deprecated `Astro.canonicalURL` | ⭐ |
| [astro/no-deprecated-astro-fetchcontent](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-deprecated-astro-fetchcontent/) | disallow using deprecated `Astro.fetchContent()` | ⭐🔧 |
| [astro/no-deprecated-astro-resolve](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-deprecated-astro-resolve/) | disallow using deprecated `Astro.resolve()` | ⭐ |
| [astro/no-deprecated-getentrybyslug](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-deprecated-getentrybyslug/) | disallow using deprecated `getEntryBySlug()` | ⭐ |
| [astro/no-exports-from-components](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-exports-from-components/) | disallow value export | ⭐ |
| [astro/no-prerender-export-outside-pages](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-prerender-export-outside-pages/) | disallow `prerender` export outside of pages/ directory | ⭐ |
| [astro/no-unused-define-vars-in-style](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-unused-define-vars-in-style/) | disallow unused `define:vars={...}` in `style` tag | ⭐ |
## Security Vulnerability
These rules relate to security vulnerabilities in Astro component code:
| Rule ID | Description | |
|:--------|:------------|:---|
| [astro/no-set-html-directive](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-set-html-directive/) | disallow use of `set:html` to prevent XSS attack | |
| [astro/no-unsafe-inline-scripts](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-unsafe-inline-scripts/) | disallow inline `<script>` without `src` to encourage CSP-safe patterns | |
## Best Practices
These rules relate to better ways of doing things to help you avoid problems:
| Rule ID | Description | |
|:--------|:------------|:---|
| [astro/no-set-text-directive](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-set-text-directive/) | disallow use of `set:text` | 🔧 |
| [astro/no-unused-css-selector](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-unused-css-selector/) | disallow selectors defined in `style` tag that don't use in HTML | |
## Stylistic Issues
These rules relate to style guidelines, and are therefore quite subjective:
| Rule ID | Description | |
|:--------|:------------|:---|
| [astro/prefer-class-list-directive](https://ota-meshi.github.io/eslint-plugin-astro/rules/prefer-class-list-directive/) | require `class:list` directives instead of `class` with expressions | 🔧 |
| [astro/prefer-object-class-list](https://ota-meshi.github.io/eslint-plugin-astro/rules/prefer-object-class-list/) | require use object instead of ternary expression in `class:list` | 🔧 |
| [astro/prefer-split-class-list](https://ota-meshi.github.io/eslint-plugin-astro/rules/prefer-split-class-list/) | require use split array elements in `class:list` | 🔧 |
| [astro/sort-attributes](https://ota-meshi.github.io/eslint-plugin-astro/rules/sort-attributes/) | enforce sorting of attributes | 🔧 |
## A11Y Extension Rules
These rules extend the rules provided by [eslint-plugin-jsx-a11y] to work well in Astro component:
(You need to install [eslint-plugin-jsx-a11y] to use the rules.)
| Rule ID | Description | |
|:--------|:------------|:---|
| [astro/jsx-a11y/alt-text](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/alt-text/) | apply `jsx-a11y/alt-text` rule to Astro components | |
| [astro/jsx-a11y/anchor-ambiguous-text](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/anchor-ambiguous-text/) | apply `jsx-a11y/anchor-ambiguous-text` rule to Astro components | |
| [astro/jsx-a11y/anchor-has-content](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/anchor-has-content/) | apply `jsx-a11y/anchor-has-content` rule to Astro components | |
| [astro/jsx-a11y/anchor-is-valid](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/anchor-is-valid/) | apply `jsx-a11y/anchor-is-valid` rule to Astro components | |
| [astro/jsx-a11y/aria-activedescendant-has-tabindex](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/aria-activedescendant-has-tabindex/) | apply `jsx-a11y/aria-activedescendant-has-tabindex` rule to Astro components | |
| [astro/jsx-a11y/aria-props](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/aria-props/) | apply `jsx-a11y/aria-props` rule to Astro components | |
| [astro/jsx-a11y/aria-proptypes](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/aria-proptypes/) | apply `jsx-a11y/aria-proptypes` rule to Astro components | |
| [astro/jsx-a11y/aria-role](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/aria-role/) | apply `jsx-a11y/aria-role` rule to Astro components | |
| [astro/jsx-a11y/aria-unsupported-elements](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/aria-unsupported-elements/) | apply `jsx-a11y/aria-unsupported-elements` rule to Astro components | |
| [astro/jsx-a11y/autocomplete-valid](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/autocomplete-valid/) | apply `jsx-a11y/autocomplete-valid` rule to Astro components | |
| [astro/jsx-a11y/click-events-have-key-events](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/click-events-have-key-events/) | apply `jsx-a11y/click-events-have-key-events` rule to Astro components | |
| [astro/jsx-a11y/control-has-associated-label](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/control-has-associated-label/) | apply `jsx-a11y/control-has-associated-label` rule to Astro components | |
| [astro/jsx-a11y/heading-has-content](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/heading-has-content/) | apply `jsx-a11y/heading-has-content` rule to Astro components | |
| [astro/jsx-a11y/html-has-lang](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/html-has-lang/) | apply `jsx-a11y/html-has-lang` rule to Astro components | |
| [astro/jsx-a11y/iframe-has-title](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/iframe-has-title/) | apply `jsx-a11y/iframe-has-title` rule to Astro components | |
| [astro/jsx-a11y/img-redundant-alt](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/img-redundant-alt/) | apply `jsx-a11y/img-redundant-alt` rule to Astro components | |
| [astro/jsx-a11y/interactive-supports-focus](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/interactive-supports-focus/) | apply `jsx-a11y/interactive-supports-focus` rule to Astro components | |
| [astro/jsx-a11y/label-has-associated-control](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/label-has-associated-control/) | apply `jsx-a11y/label-has-associated-control` rule to Astro components | |
| [astro/jsx-a11y/lang](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/lang/) | apply `jsx-a11y/lang` rule to Astro components | |
| [astro/jsx-a11y/media-has-caption](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/media-has-caption/) | apply `jsx-a11y/media-has-caption` rule to Astro components | |
| [astro/jsx-a11y/mouse-events-have-key-events](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/mouse-events-have-key-events/) | apply `jsx-a11y/mouse-events-have-key-events` rule to Astro components | |
| [astro/jsx-a11y/no-access-key](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-access-key/) | apply `jsx-a11y/no-access-key` rule to Astro components | |
| [astro/jsx-a11y/no-aria-hidden-on-focusable](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-aria-hidden-on-focusable/) | apply `jsx-a11y/no-aria-hidden-on-focusable` rule to Astro components | |
| [astro/jsx-a11y/no-autofocus](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-autofocus/) | apply `jsx-a11y/no-autofocus` rule to Astro components | |
| [astro/jsx-a11y/no-distracting-elements](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-distracting-elements/) | apply `jsx-a11y/no-distracting-elements` rule to Astro components | |
| [astro/jsx-a11y/no-interactive-element-to-noninteractive-role](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-interactive-element-to-noninteractive-role/) | apply `jsx-a11y/no-interactive-element-to-noninteractive-role` rule to Astro components | |
| [astro/jsx-a11y/no-noninteractive-element-interactions](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-noninteractive-element-interactions/) | apply `jsx-a11y/no-noninteractive-element-interactions` rule to Astro components | |
| [astro/jsx-a11y/no-noninteractive-element-to-interactive-role](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-noninteractive-element-to-interactive-role/) | apply `jsx-a11y/no-noninteractive-element-to-interactive-role` rule to Astro components | |
| [astro/jsx-a11y/no-noninteractive-tabindex](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-noninteractive-tabindex/) | apply `jsx-a11y/no-noninteractive-tabindex` rule to Astro components | |
| [astro/jsx-a11y/no-redundant-roles](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-redundant-roles/) | apply `jsx-a11y/no-redundant-roles` rule to Astro components | |
| [astro/jsx-a11y/no-static-element-interactions](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/no-static-element-interactions/) | apply `jsx-a11y/no-static-element-interactions` rule to Astro components | |
| [astro/jsx-a11y/prefer-tag-over-role](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/prefer-tag-over-role/) | apply `jsx-a11y/prefer-tag-over-role` rule to Astro components | |
| [astro/jsx-a11y/role-has-required-aria-props](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/role-has-required-aria-props/) | apply `jsx-a11y/role-has-required-aria-props` rule to Astro components | |
| [astro/jsx-a11y/role-supports-aria-props](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/role-supports-aria-props/) | apply `jsx-a11y/role-supports-aria-props` rule to Astro components | |
| [astro/jsx-a11y/scope](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/scope/) | apply `jsx-a11y/scope` rule to Astro components | |
| [astro/jsx-a11y/tabindex-no-positive](https://ota-meshi.github.io/eslint-plugin-astro/rules/jsx-a11y/tabindex-no-positive/) | apply `jsx-a11y/tabindex-no-positive` rule to Astro components | |
## Extension Rules
These rules extend the rules provided by ESLint itself to work well in Astro component:
| Rule ID | Description | |
|:--------|:------------|:---|
| [astro/semi](https://ota-meshi.github.io/eslint-plugin-astro/rules/semi/) | Require or disallow semicolons instead of ASI | 🔧 |
## Deprecated
- ⚠️ We're going to remove deprecated rules in the next major release. Please migrate to successor/new rules.
- 😇 We don't fix bugs which are in deprecated rules since we don't have enough resources.
| Rule ID | Description | |
|:--------|:------------|:---|
| [astro/no-omitted-end-tags](https://ota-meshi.github.io/eslint-plugin-astro/rules/no-omitted-end-tags/) | (no replacement) |
| [astro/valid-compile](https://ota-meshi.github.io/eslint-plugin-astro/rules/valid-compile/) | (no replacement) |
<!--RULES_TABLE_END-->
<!--RULES_SECTION_END-->
## 🚥 Versioning policy
This plugin follows [Semantic Versioning].
However, please note that we do not follow [ESLint's Semantic Versioning Policy].
In minor version releases, this plugin may change the sharable configs provided by the plugin or the default behavior of the plugin's rules in order to add features to the plugin. Because we want to add many features to the plugin soon, so that users can easily take advantage of new features in Astro.
According to our policy, any minor update may report more linting errors than the previous release. As such, we recommend using the [tilde (`~`)](https://semver.npmjs.com/#syntax-examples) in `package.json` to guarantee the results of your builds.
[Semantic Versioning]: https://semver.org/
[ESLint's Semantic Versioning Policy]: https://github.com/eslint/eslint#semantic-versioning-policy
<!--DOCS_IGNORE_START-->
## 🍻 Contributing
Welcome contributing!
Please use GitHub's Issues/PRs.
### Development Tools
- `npm test` runs tests and measures coverage.
- `npm run update` runs in order to update readme and recommended configuration.
### Working With Rules
This plugin uses [astro-eslint-parser](https://github.com/ota-meshi/astro-eslint-parser) for the parser. Check [here](https://ota-meshi.github.io/astro-eslint-parser/) to find out about AST.
<!--DOCS_IGNORE_END-->
## ❤️ Supporting
If you are willing to see that this package continues to be maintained, please consider sponsoring me.
[](https://github.com/sponsors/ota-meshi)
## 🔒 License
See the [LICENSE](LICENSE) file for license rights and limitations (MIT).
[eslint]: https://eslint.org/
[astro components]: https://docs.astro.build/en/core-concepts/astro-components/