eslint-plugin-astro

1.7.0 verified Sat Apr 25 auth: no javascript

An ESLint plugin for linting Astro components. Version 1.7.0 is the latest stable release, with active development and releases roughly monthly. It lints frontmatter, HTML templates, JSX-like expressions, client-side scripts, and directives. Supports both flat config (eslint.config.js) and legacy config (.eslintrc). Ships TypeScript types. Requires eslint >=8.57.0 and Node.js ^18.18.0 || ^20.9.0 || >=21.1.0. Differentiators: official AST-based parsing for Astro, rules for sort-attributes, no-unsafe-inline-scripts, and no-prerender-export-outside-pages. Community-maintained by ota-meshi.

Common errors

error Error: Cannot find module 'eslint-plugin-astro' ↓

cause Missing installed plugin or incorrect import in CJS context.

fix

npm install --save-dev eslint-plugin-astro (ESM). If using require(), switch to import or downgrade to 0.x.

error Error: 'astro/no-unsafe-inline-scripts' rule is not defined ↓

cause Rule added in v1.4.0; using older version.

fix

Upgrade eslint-plugin-astro to >=1.4.0: npm install eslint-plugin-astro@latest

error Parsing error: The keyword 'export' is reserved ↓

cause Using ESLint parser that doesn't understand Astro syntax (e.g., default parser).

fix

Use the plugin's bundled parser: in flat config, include eslintPluginAstro.configs.recommended. In legacy config, set 'parser': 'astro-eslint-parser'.

error TypeError: eslintPluginAstro.configs.recommended is not iterable ↓

cause Using spread operator on configs object in flat config, but configs might not be array?

fix

Ensure you are spreading an array: ...eslintPluginAstro.configs['flat/recommended'] (or check version).

Warnings

gotcha Flat config (eslint.config.js) vs legacy (.eslintrc) – the plugin supports both, but default export is for flat config; legacy uses 'plugin:astro/recommended' in extends. ↓

fix For flat config: import eslintPluginAstro from 'eslint-plugin-astro' and spread configs. For legacy: use 'extends': ['plugin:astro/recommended'].

breaking ESM only since v1.0.0. No CommonJS export; require() will fail. ↓

fix Use import syntax (ESM). If you must use require, install an older version (e.g., 0.x).

deprecated Some rules are marked as deprecated in future versions; check docs. ↓

fix Review rule documentation and migrate to recommended replacements.

gotcha TypeScript support requires @typescript-eslint/parser; without it, TypeScript frontmatter is not parsed. ↓

fix Install @typescript-eslint/parser and include it in parser options for .astro files.

gotcha A11Y rules require optional dependency eslint-plugin-jsx-a11y; if not installed, those rules will error at runtime. ↓

fix Install eslint-plugin-jsx-a11y or disable the A11Y rules.

Install

npm install eslint-plugin-astro

yarn add eslint-plugin-astro

pnpm add eslint-plugin-astro

Imports

eslintPluginAstro

wrong

const eslintPluginAstro = require('eslint-plugin-astro');

correct

import eslintPluginAstro from 'eslint-plugin-astro';

Default export for flat config. ESM-only; no CommonJS export.

astro.configs.recommended

wrong

const { configs: { recommended } } = require('eslint-plugin-astro');

correct

import eslintPluginAstro from 'eslint-plugin-astro';
export default [...eslintPluginAstro.configs.recommended];

Access configs from the default import. Legacy .eslintrc uses 'extends': ['plugin:astro/recommended'].

rules

wrong

const { rules } = require('eslint-plugin-astro');

correct

import eslintPluginAstro from 'eslint-plugin-astro';
const rules = eslintPluginAstro.rules;

Rules are on the default export object. TypeScript: import type { Rule } from 'eslint-plugin-astro'.

Quickstart

Shows flat config setup with recommended Astro rules and TypeScript integration.

// eslint.config.js (flat config)
import eslintPluginAstro from 'eslint-plugin-astro';
import js from '@eslint/js';
import tseslint from 'typescript-eslint';

export default [
  js.configs.recommended,
  ...eslintPluginAstro.configs.recommended,
  ...tseslint.configs.recommended,
  {
    rules: {
      'astro/no-unsafe-inline-scripts': 'error',
    },
  },
];

// .astro file example
// Comment: also works with .eslintrc.cjs: module.exports = { extends: ['plugin:astro/recommended'] }