# astro-eslint-parser

> Astro component parser for ESLint

Latest version **3.1.0** (published 2026-08-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install astro-eslint-parser
pnpm add astro-eslint-parser
yarn add astro-eslint-parser
bun add astro-eslint-parser
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.0 |
| Published | 2026-08-13 |
| First published | 2022-04-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^22.22.3 \|\| ^24.16.0 \|\| >=26.3.0 |
| Dependencies | 9 |
| Unpacked size | 99 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 88 |
| Author | Yosuke Ota |
| Maintainers | ota-meshi |
| Keywords | astro, astrojs, eslint, parser |

## Links

- npm: https://www.npmjs.com/package/astro-eslint-parser
- Repository: https://github.com/ota-meshi/astro-eslint-parser
- Homepage: https://github.com/ota-meshi/astro-eslint-parser#readme
- Issues: https://github.com/ota-meshi/astro-eslint-parser/issues
- Funding: https://github.com/sponsors/ota-meshi
- npm.io page: https://npm.io/package/astro-eslint-parser

## Dependencies (9)

- [debug](https://npm.io/package/debug.md) ^4.4.3
- [espree](https://npm.io/package/espree.md) ^11.2.0
- [semver](https://npm.io/package/semver.md) ^7.8.4
- [tinyglobby](https://npm.io/package/tinyglobby.md) ^0.2.17
- [eslint-scope](https://npm.io/package/eslint-scope.md) ^9.1.2
- [eslint-visitor-keys](https://npm.io/package/eslint-visitor-keys.md) ^5.0.1
- [@astrojs/compiler-rs](https://npm.io/package/@astrojs/compiler-rs.md) ^0.4.0
- [@typescript-eslint/types](https://npm.io/package/@typescript-eslint/types.md) ^8.61.0
- [@typescript-eslint/scope-manager](https://npm.io/package/@typescript-eslint/scope-manager.md) ^8.61.0

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 3.1.0 (latest) — 2026-08-13
- 3.0.0 — 2026-07-12
- 2.1.0 — 2026-06-24
- 2.0.0 — 2026-06-21
- 1.4.0 — 2026-03-24
- 1.3.2 — 2026-03-24
- 1.3.1 — 2026-03-24
- 1.3.0 — 2026-02-14
- 1.2.2 — 2025-03-21
- 1.2.1 — 2025-01-25
- 1.2.0 — 2025-01-25
- 1.1.0 — 2024-11-12
- 1.0.3 — 2024-09-12
- 1.0.2 — 2024-05-02
- 1.0.1 — 2024-04-26
- … 65 more at https://npm.io/package/astro-eslint-parser/versions

## README

# astro-eslint-parser

[Astro] component parser for [ESLint].  
You can check it on [Online DEMO](https://ota-meshi.github.io/astro-eslint-parser/playground).

[![sponsors](https://img.shields.io/badge/-Sponsor-fafbfc?logo=GitHub%20Sponsors)](https://github.com/sponsors/ota-meshi)

[![NPM license](https://img.shields.io/npm/l/astro-eslint-parser.svg)](https://www.npmjs.com/package/astro-eslint-parser)
[![NPM version](https://img.shields.io/npm/v/astro-eslint-parser.svg)](https://www.npmjs.com/package/astro-eslint-parser)
[![NPM downloads](https://img.shields.io/badge/dynamic/json.svg?label=downloads&colorB=green&suffix=/day&query=$.downloads&uri=https://api.npmjs.org//downloads/point/last-day/astro-eslint-parser&maxAge=3600)](http://www.npmtrends.com/astro-eslint-parser)
[![NPM downloads](https://img.shields.io/npm/dw/astro-eslint-parser.svg)](http://www.npmtrends.com/astro-eslint-parser)
[![NPM downloads](https://img.shields.io/npm/dm/astro-eslint-parser.svg)](http://www.npmtrends.com/astro-eslint-parser)
[![NPM downloads](https://img.shields.io/npm/dy/astro-eslint-parser.svg)](http://www.npmtrends.com/astro-eslint-parser)
[![NPM downloads](https://img.shields.io/npm/dt/astro-eslint-parser.svg)](http://www.npmtrends.com/astro-eslint-parser)
[![Build Status](https://github.com/ota-meshi/astro-eslint-parser/workflows/CI/badge.svg?branch=main)](https://github.com/ota-meshi/astro-eslint-parser/actions?query=workflow%3ACI)
[![Coverage Status](https://coveralls.io/repos/github/ota-meshi/astro-eslint-parser/badge.svg?branch=main)](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.


## :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
```

This package is ESM-only. Use `import` to load it from JavaScript config files.
CommonJS `require("astro-eslint-parser")` is not supported.

## 📖 Usage

**First, we recommend using [eslint-plugin-astro] rather than just the parser.**  
The following examples are for introducing only the parser. This is not useful for most people. It can be useful if you create your own plugin.

1. Configure `languageOptions.parser` for `.astro` files in your `eslint.config.*` file.

    ```js
    import * as astroParser from "astro-eslint-parser"

    export default [
        {
            files: ["**/*.astro"],
            languageOptions: {
                parser: astroParser,
            },
        },
    ]
    ```

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.

### Public API

Import this package from the package root:

```js
import * as astroParser from "astro-eslint-parser"
```

## 🔧 Options

`parserOptions` has the same properties as what [espree](https://github.com/eslint/espree#usage), the default parser of ESLint, is supporting.
For example:

```js
import * as astroParser from "astro-eslint-parser"

export default [
    {
        files: ["**/*.astro"],
        languageOptions: {
            parser: astroParser,
            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:

```js
import * as astroParser from "astro-eslint-parser"

export default [
    {
        files: ["**/*.astro"],
        languageOptions: {
            parser: astroParser,
            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
import tsParser from "@typescript-eslint/parser"
import * as astroParser from "astro-eslint-parser"

export default [
    {
        files: ["**/*.astro"],
        languageOptions: {
            parser: astroParser,
            parserOptions: {
                parser: tsParser,
                project: "path/to/your/tsconfig.json",
                extraFileExtensions: [".astro"],
            },
        },
    },
]
```

You can also give different parsers for different languages.

```js
import tsParser from "@typescript-eslint/parser"
import * as astroParser from "astro-eslint-parser"

export default [
    {
        files: ["**/*.astro"],
        languageOptions: {
            parser: astroParser,
            parserOptions: {
                parser: {
                    ts: tsParser,
                    js: "espree",
                },
            },
        },
    },
]
```

## :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.

[![sponsors](https://img.shields.io/badge/-Sponsor-fafbfc?logo=GitHub%20Sponsors)](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/

---
_Source: https://npm.io/package/astro-eslint-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._