astro-eslint-parser

astro-eslint-parser

Astro component parser for ESLint.
You can check it on Online DEMO.

This parser is in the experimental stages of development.

At least it works fine with a 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

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.

   {
       "extends": "eslint:recommended",
       "overrides": [
           {
               "files": ["*.astro"],
               "parser": "astro-eslint-parser"
           }
       ]
   }
   

2. If you have specified the extension in the CLI, add .astro as well.

   $ eslint "src/**/*.{js,astro}"
   # or
   $ eslint src --ext .js,.astro
   

The commit diff here is an example of introducing this parser to the astro.build repository.

🔧 Options

parserOptions has the same properties as what espree, the default parser of ESLint, is supporting. For example:

{
    "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:

{
    "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.

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.

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

{
    "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.

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

:hammer_and_wrench: Usage for Custom Rules / Plugins

• TBA
• You can check the AST in the Online DEMO. 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.

:lock: License

See the LICENSE file for license rights and limitations (MIT).

Changelog

1.0.1

Patch Changes

• #318 7126ccc Thanks @ota-meshi! - fix: crash in scope analysis when using espree