astro

> ESLint flat config for Astro with TypeScript. Extends @jmlweb/eslint-config-base with eslint-plugin-astro rules for .astro files.

> ✅ Recommended: Oxlint cannot lint .astro templates, so this package is the way to lint them. In a project migrated to Oxlint, lint everything else with @jmlweb/oxlint-config-base and only .astro files with ESLint; see the migration guide.

✨ Features

🚀 Astro rules: eslint-plugin-astro recommended config
📝 .astro parsing: TypeScript parser for frontmatter, with type-checked rules disabled where .astro has no type info
🔒 Strict TypeScript: everything from @jmlweb/eslint-config-base for .ts and .tsx
📦 Import sorting: imports and exports sorted in .astro, .ts and .tsx
🎨 Prettier compatible: disables rules that conflict with Prettier

📦 Installation

npm install --save-dev @jmlweb/eslint-config-astro @jmlweb/eslint-config-base eslint @eslint/js typescript-eslint eslint-config-prettier eslint-plugin-simple-import-sort eslint-plugin-astro

> 💡 Upgrading? See the Migration Guide.

🚀 Quick Start

import astroConfig from '@jmlweb/eslint-config-astro';

export default [
  ...astroConfig,
  // Project-specific overrides
];

💡 Examples

Test overrides and ignores

import astroConfig from '@jmlweb/eslint-config-astro';

export default [
  ...astroConfig,
  {
    files: ['**/*.test.ts'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
      'no-console': 'off',
    },
  },
  {
    ignores: ['dist/', '.astro/', 'node_modules/'],
  },
];

Tune Astro rules

import astroConfig from '@jmlweb/eslint-config-astro';

export default [
  ...astroConfig,
  {
    files: ['**/*.astro'],
    rules: {
      'astro/no-unused-define-vars-in-style': 'warn',
    },
  },
];

📋 Configuration Details

Files	Applied
`*/.astro`	`astro` recommended, TypeScript parser, type-checked rules off, sorting
`*/.ts`, `*/.tsx`	Strict TypeScript from `base`, import and export sorting

Included

✅ Everything from @jmlweb/eslint-config-base
✅ eslint-plugin-astro recommended rules
✅ .astro files parsed with @typescript-eslint/parser and .astro as an extra file extension
✅ Prettier conflict resolution

Type-checked rules are disabled for .astro files because astro-eslint-parser provides no type information.

🔄 Import Sorting

Imports are sorted and type-only imports are enforced.

Before:

import { Component } from './component';
import type { User } from './types';
import fs from 'fs';

After eslint --fix:

import fs from 'fs';
import type { User } from './types';
import { Component } from './component';

🎯 When to Use

✅ Astro projects written in TypeScript
✅ Linting .astro files alongside Oxlint in a migrated project
✅ Strict type-aware linting for .ts files in Astro projects

For other TypeScript projects use @jmlweb/eslint-config-base, or @jmlweb/eslint-config-react for React.

🔧 Extending the Configuration

Spread the config, then add objects after it. Later entries win.

import astroConfig from '@jmlweb/eslint-config-astro';

export default [
  ...astroConfig,
  {
    files: ['src/pages/**/*.astro'],
    rules: {
      'no-console': 'off',
    },
  },
];

📝 Usage with Scripts

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  }
}

npm run lint

📋 Requirements

Node.js >= 22.12.0
ESLint ^9.0.0 || ^10.0.0 (flat config)
TypeScript project with a tsconfig.json (versions supported by typescript-eslint 8)

📦 Peer Dependencies

eslint (^9.0.0 || ^10.0.0)
@eslint/js (^9.0.0 || ^10.0.0)
typescript-eslint (^8.0.0)
eslint-config-prettier (^9.1.0 || ^10.0.0)
eslint-plugin-astro (^1.5.0 || ^2.0.0 || ^3.0.0)
eslint-plugin-simple-import-sort (^12.0.0 || ^13.0.0 || ^14.0.0)
@jmlweb/eslint-config-base (^3.0.3)

@jmlweb/eslint-config-base: TypeScript config (extended by this package, maintenance mode)
@jmlweb/oxlint-config-base: Oxlint config for the non-.astro files
@jmlweb/tsconfig-astro: TypeScript config for Astro
@jmlweb/prettier-config-base: Prettier config (maintenance mode)

🔄 Migration Guide

1.x to 2.0

Node.js 18 and 20 are end-of-life. Node.js >= 22.12.0 is now required: it is the first Node.js 22 release that can require() ES modules without a flag, which the CommonJS build needs to load ESM-only plugins. Peer ranges were also widened (eslint-plugin-astro 2 and 3, eslint-plugin-simple-import-sort 13 and 14).

Upgrade Node.js to 22.12.0 or later.
Update the package: npm install --save-dev @jmlweb/eslint-config-astro@latest.

See the Changelog.

📄 License

MIT