@jmlweb/eslint-config-astro

ESLint configuration for Astro projects with TypeScript. Extends @jmlweb/eslint-config-base with Astro-specific rules and best practices for .astro files.

✨ Features

• 🔒 Strict Type Checking: Inherits all strict TypeScript rules from base config
• 🚀 Astro Support: Enforces Astro-specific rules and patterns
• 📝 Astro File Handling: Proper linting for .astro files
• 📦 Import Management: Enforces type-only imports with inline style + automatic sorting
• 🎯 Code Quality: Prevents common Astro pitfalls and anti-patterns
• 🎨 Prettier Integration: Disables all ESLint rules that conflict with Prettier
• 🚀 Flat Config: Uses ESLint 9+ flat config format (latest stable)

📦 Installation

pnpm add -D @jmlweb/eslint-config-astro eslint @eslint/js typescript-eslint eslint-config-prettier eslint-plugin-astro eslint-plugin-simple-import-sort @jmlweb/eslint-config-base

💡 Upgrading from a previous version? See the Migration Guide for breaking changes and upgrade instructions.

🚀 Quick Start

Create an eslint.config.js file in your project root:

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

export default [
  ...astroConfig,
  // Add your project-specific overrides here
];

💡 Examples

Basic Setup

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

export default [...astroConfig];

With Project-Specific Overrides

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

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

With Custom Astro Settings

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

export default [
  ...astroConfig,
  {
    files: ['**/*.astro'],
    rules: {
      // Customize Astro-specific rules
      'astro/no-conflict-set-directives': 'error',
      'astro/no-unused-define-vars-in-style': 'warn',
    },
  },
];

📋 Configuration Details

Astro Files

This configuration applies Astro-specific rules to:

• **/*.astro - Astro component files

TypeScript Files

TypeScript rules are also applied to:

• **/*.ts - TypeScript files
• **/*.tsx - TypeScript React files (if used in Astro project)

Key Rules Enforced

| Rule | Level | Description | | -------------------------------------- | ------- | ----------------------------------- | | astro/no-conflict-set-directives | error | Prevents conflicting set directives | | astro/no-unused-define-vars-in-style | warn | Warns about unused CSS variables | | simple-import-sort/imports | error | Enforces import sorting | | simple-import-sort/exports | error | Enforces export sorting |

What's Included

• ✅ All TypeScript ESLint rules from @jmlweb/eslint-config-base
• ✅ Astro recommended rules from eslint-plugin-astro
• ✅ Proper handling of .astro files with TypeScript parser
• ✅ Automatic import/export sorting
• ✅ Prettier conflict resolution

🔄 Import Sorting

The configuration automatically sorts imports and enforces type-only imports:

Before:

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

After auto-fix:

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

Fix import order automatically:

pnpm exec eslint --fix .

🤔 Why Use This?

Philosophy: Astro components should follow Astro's mental model - islands of interactivity with server-first rendering.

This package extends the base TypeScript config with Astro-specific rules that enforce best practices for .astro files, prevent common pitfalls with Astro's unique component model, and ensure proper usage of Astro directives.

Design Decisions

Astro Plugin (eslint-plugin-astro): Enforces Astro-specific rules and patterns

• Why: Astro has a unique component format that blends frontmatter, markup, and optional client-side interactivity. The plugin catches misuse of directives, style conflicts, and component structure issues
• Trade-off: Additional rules specific to Astro, but prevents framework-specific bugs
• When to override: When you have a legitimate reason to deviate from Astro conventions (rare)

Astro File Support: Properly lints .astro files with awareness of their structure

• Why: .astro files have three sections (frontmatter, template, style) that need different parsing. Standard linters don't understand this format
• Trade-off: None - this is essential for Astro development
• When to override: Never - Astro files require Astro-aware linting

Extends Base TypeScript Config: Inherits all strict type checking rules for TypeScript in frontmatter

• Why: Astro components often contain complex TypeScript logic in frontmatter. Strict typing catches bugs early
• Trade-off: More verbose frontmatter code, but prevents runtime errors
• When to override: Follow the same guidelines as the base TypeScript config

🎯 When to Use

Use this configuration when you want:

• ✅ Astro project development with TypeScript
• ✅ Maximum type safety with Astro
• ✅ Strict code quality standards for Astro code
• ✅ Consistent Astro patterns across the team
• ✅ Prevention of common Astro pitfalls

For non-Astro TypeScript projects, use @jmlweb/eslint-config-base instead.

For React projects, use @jmlweb/eslint-config-react instead.

🔧 Extending the Configuration

You can extend or override the configuration for your specific needs:

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

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

📝 Usage with Scripts

Add linting scripts to your package.json:

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

Then run:

pnpm lint      # Lint all files
pnpm lint:fix  # Fix auto-fixable issues

📋 Requirements

• Node.js >= 20.11.0 (required for import.meta.dirname in config files)
• ESLint >= 9.0.0 (flat config format)
• TypeScript project with tsconfig.json
• Astro >= 4.0.0
• TypeScript project service enabled (automatic with this config)

📦 Peer Dependencies

This package requires the following peer dependencies:

• eslint (^9.0.0)
• @eslint/js (^9.0.0)
• typescript-eslint (^8.0.0)
• eslint-config-prettier (^9.1.0)
• eslint-plugin-astro (^1.5.0)
• eslint-plugin-simple-import-sort (^12.0.0)
• @jmlweb/eslint-config-base (^2.0.2)

🔗 Related Packages

Internal Packages

• @jmlweb/eslint-config-base - Base TypeScript ESLint config (extended by this package)
• @jmlweb/tsconfig-astro - TypeScript configuration for Astro projects
• @jmlweb/prettier-config-base - Prettier config for consistent formatting

External Tools

• ESLint - Pluggable linting utility for JavaScript and TypeScript
• Astro - The web framework for content-driven websites
• eslint-plugin-astro - ESLint plugin for Astro components
• Prettier Plugin Astro - Prettier plugin for .astro files

🔄 Migration Guide

Upgrading to a New Version

Note: If no breaking changes were introduced in a version, it's safe to upgrade without additional steps.

No breaking changes have been introduced yet. This package follows semantic versioning. When breaking changes are introduced, detailed migration instructions will be provided here.

For version history, see the Changelog.

Need Help? If you encounter issues during migration, please open an issue.

📜 Changelog

See CHANGELOG.md for version history and release notes.

📄 License

MIT