{"id":12840,"library":"astro-eslint-parser","title":"ESLint Parser for Astro Components","description":"astro-eslint-parser is a specialized parser that enables ESLint to understand and lint `.astro` component files. It allows developers to integrate Astro projects with their existing ESLint configurations, providing linting for scripts embedded within Astro components, including client-side scripts and component scripts. The current stable version is 1.4.0, with regular patch and minor releases to improve compatibility with newer Astro compiler versions, ESLint, and TypeScript-ESLint. Its primary differentiator is its dedicated support for the unique syntax of Astro files, making it a crucial component for maintaining code quality in Astro projects, often used in conjunction with `eslint-plugin-astro` for a complete linting solution.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/ota-meshi/astro-eslint-parser","tags":["javascript","astro","astrojs","eslint","parser","typescript"],"install":[{"cmd":"npm install astro-eslint-parser","lang":"bash","label":"npm"},{"cmd":"yarn add astro-eslint-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add astro-eslint-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is an ESLint parser and requires ESLint to function.","package":"eslint","optional":false},{"reason":"Often used as a sub-parser for TypeScript code within Astro components, configured via `parserOptions.parser`.","package":"@typescript-eslint/parser","optional":true},{"reason":"Internally used for parsing Astro components; compatibility with specific versions is crucial.","package":"@astrojs/compiler","optional":false}],"imports":[{"note":"This package is not imported directly into JavaScript/TypeScript files by end-users. It's configured in ESLint's `.eslintrc` file.","wrong":"import { Parser } from 'astro-eslint-parser'","symbol":"parser configuration","correct":"{ \"parser\": \"astro-eslint-parser\" }"},{"note":"To lint TypeScript code within Astro components, explicitly specify `@typescript-eslint/parser` in `parserOptions.parser`.","wrong":"{ \"parserOptions\": { \"typescript\": true } }","symbol":"TypeScript sub-parser","correct":"{ \"parserOptions\": { \"parser\": \"@typescript-eslint/parser\" } }"},{"note":"For most use cases, it's recommended to use `eslint-plugin-astro` which internally uses `astro-eslint-parser` and provides sensible defaults and rules.","wrong":"import { AstroPlugin } from 'eslint-plugin-astro'","symbol":"ESLint plugin integration","correct":"{ \"extends\": [\"plugin:astro/recommended\"] }"}],"quickstart":{"code":"npm install --save-dev eslint astro-eslint-parser eslint-plugin-astro\n\n// .eslintrc.cjs\nmodule.exports = {\n  root: true,\n  env: {\n    browser: true,\n    es2020: true,\n    node: true\n  },\n  extends: [\n    'eslint:recommended',\n    'plugin:astro/recommended',\n    'plugin:@typescript-eslint/recommended' // If using TypeScript\n  ],\n  parser: 'astro-eslint-parser',\n  parserOptions: {\n    ecmaVersion: 'latest',\n    sourceType: 'module',\n    project: './tsconfig.json', // Only if using @typescript-eslint/parser with project-level rules\n    extraFileExtensions: ['.astro'],\n    parser: '@typescript-eslint/parser' // Enable TypeScript parsing within Astro files\n  },\n  overrides: [\n    {\n      files: ['*.astro'],\n      parser: 'astro-eslint-parser',\n      parserOptions: {\n        parser: '@typescript-eslint/parser' // Re-specify for overrides to ensure TS parsing\n      }\n    }\n  ]\n};\n\n// Add a script to your package.json:\n// \"lint\": \"eslint \\\"**/*.{js,ts,astro}\\\" --cache --fix\"\n","lang":"typescript","description":"This quickstart demonstrates how to install `astro-eslint-parser` and configure ESLint, including `eslint-plugin-astro` and TypeScript support, to lint Astro files."},"warnings":[{"fix":"Stay updated with releases and test configurations thoroughly after upgrades. Report issues to the GitHub repository.","message":"This parser is considered to be in 'experimental stages' of development. While functional, breaking changes or unexpected behavior might occur between minor versions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `astro-eslint-parser` is updated to a version explicitly supporting your `@astrojs/compiler` version, as indicated in release notes (e.g., v1.4.0 added support for `@astrojs/compiler` v3).","message":"Compatibility with `@astrojs/compiler` is crucial. Updates to the Astro compiler might require `astro-eslint-parser` updates to function correctly, potentially breaking linting if not aligned.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"It is highly recommended to use `eslint-plugin-astro` alongside this parser, as it provides rules and configurations to correctly lint all script contexts within Astro components, including `<script>` tags.","message":"Using the parser alone only lints the script of `.astro` files. It does not lint scripts inside `<script>` tags by itself.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Keep `astro-eslint-parser` updated to its latest version to ensure compatibility. For example, v1.3.0 improved compatibility with ESLint v10, and v1.0.3 fixed support for `typescript-eslint@8`.","message":"Updates to `@typescript-eslint/parser` or ESLint itself (e.g., ESLint v10) can sometimes require corresponding updates or configuration adjustments in `astro-eslint-parser`.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `parserOptions.sourceType` is set to `module` in your `.eslintrc` file, especially within the `overrides` section for `*.astro` files.","cause":"ESLint is configured for CommonJS (`sourceType: script`) but encountered ESM syntax in an Astro file.","error":"Parsing error: 'import' and 'export' may only appear at the top level (If using CommonJS config with `sourceType: module`)"},{"fix":"Install the TypeScript ESLint parser: `npm install --save-dev @typescript-eslint/parser`.","cause":"You've configured `parserOptions.parser: '@typescript-eslint/parser'` but the package is not installed.","error":"Error: Cannot find module '@typescript-eslint/parser'"},{"fix":"Ensure `astro-eslint-parser` is correctly specified as the `parser` for `*.astro` files in your ESLint configuration's `overrides` section.","cause":"ESLint is attempting to parse Astro's HTML-like syntax or components with a standard JavaScript parser.","error":"Parsing error: Unexpected token <"},{"fix":"Update `astro-eslint-parser` to the latest version. Check the Astro component for valid HTML/JSX structure, and report specific cases to the maintainers if the issue persists with valid code.","cause":"This parser sometimes has trouble with malformed HTML or specific Astro component syntax, especially when it's experimental.","error":"Parsing error: Element is missing closing tag. (When linting Astro components)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}