@jmlweb/eslint-config-astro 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @jmlweb/eslint-config-astro
 
+## 1.0.5
+
+### Patch Changes
+
+- 30f8ffb: Add "Why Use This?" sections to package READMEs explaining configuration philosophy and design decisions
+- Updated dependencies [30f8ffb]
+  - @jmlweb/eslint-config-base@2.0.5
+
+## 1.0.4
+
+### Patch Changes
+
+- 4a9ece1: Update documentation to use pnpm commands instead of npm
+- Updated dependencies [4a9ece1]
+  - @jmlweb/eslint-config-base@2.0.4
+
 ## 1.0.3
 
 ### Patch Changes

package/README.md

@@ -22,7 +22,7 @@
 ## 📦 Installation
 
 ```bash
-npm install --save-dev @jmlweb/eslint-config-astro eslint @eslint/js typescript-eslint eslint-config-prettier eslint-plugin-astro eslint-plugin-simple-import-sort @jmlweb/eslint-config-base
+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](#-migration-guide) for breaking changes and upgrade instructions.
@@ -148,9 +148,35 @@ import { Component } from './component';
 Fix import order automatically:
 
 ```bash
-npx eslint --fix .
+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:
@@ -203,8 +229,8 @@ Add linting scripts to your `package.json`:
 Then run:
 
 ```bash
-npm run lint      # Lint all files
-npm run lint:fix  # Fix auto-fixable issues
+pnpm lint      # Lint all files
+pnpm lint:fix  # Fix auto-fixable issues
 ```
 
 ## 📋 Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmlweb/eslint-config-astro",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "ESLint configuration for Astro projects with TypeScript. Extends @jmlweb/eslint-config-base with Astro-specific rules.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -52,10 +52,10 @@
     "eslint-plugin-astro": "^1.5.0",
     "eslint-plugin-simple-import-sort": "^12.0.0",
     "typescript-eslint": "^8.0.0",
-    "@jmlweb/eslint-config-base": "2.0.3"
+    "@jmlweb/eslint-config-base": "2.0.5"
   },
   "dependencies": {
-    "@jmlweb/eslint-config-base": "2.0.3"
+    "@jmlweb/eslint-config-base": "2.0.5"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
@@ -67,8 +67,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.34.1",
-    "@jmlweb/eslint-config-base": "2.0.3",
-    "@jmlweb/tsconfig-internal": "0.0.1"
+    "@jmlweb/tsconfig-internal": "0.0.1",
+    "@jmlweb/eslint-config-base": "2.0.5"
   },
   "scripts": {
     "build": "tsup",