@jmlweb/eslint-config-react 2.0.4 → 2.0.6

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @jmlweb/eslint-config-react
 
+## 2.0.6
+
+### 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
+
+## 2.0.5
+
+### Patch Changes
+
+- 4a9ece1: Update documentation to use pnpm commands instead of npm
+- Updated dependencies [4a9ece1]
+  - @jmlweb/eslint-config-base@2.0.4
+
 ## 2.0.4
 
 ### Patch Changes

package/README.md

@@ -23,7 +23,7 @@
 ## 📦 Installation
 
 ```bash
-npm install --save-dev @jmlweb/eslint-config-react eslint @eslint/js typescript-eslint eslint-config-prettier eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-simple-import-sort @jmlweb/eslint-config-base
+pnpm add -D @jmlweb/eslint-config-react eslint @eslint/js typescript-eslint eslint-config-prettier eslint-plugin-react eslint-plugin-react-hooks 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.
@@ -156,9 +156,47 @@ import { Component } from './component';
 Fix import order automatically:
 
 ```bash
-npx eslint --fix .
+pnpm exec eslint --fix .
 ```
 
+## 🤔 Why Use This?
+
+> **Philosophy**: React components should be predictable, composable, and easy to reason about. Strict linting catches bugs before they reach production.
+
+This package extends the base TypeScript config with React-specific rules that enforce best practices, prevent common pitfalls, and ensure proper Hook usage. React's declarative nature requires different patterns than traditional imperative code.
+
+### Design Decisions
+
+**React Hooks Rules (`eslint-plugin-react-hooks`)**: Enforces Rules of Hooks and exhaustive dependencies
+
+- **Why**: Hooks rely on call order and closure capture. Violating Hook rules causes subtle bugs that are hard to debug. Exhaustive dependencies prevent stale closures and missing reactive updates
+- **Trade-off**: May require adding dependencies you think are unnecessary, but this prevents bugs from stale values
+- **When to override**: Never for rules of hooks. For exhaustive deps, only when you understand the implications (use `eslint-disable-next-line` with a comment explaining why)
+
+**JSX Accessibility (`eslint-plugin-jsx-a11y`)**: Enforces accessibility best practices (included via recommended)
+
+- **Why**: Accessibility is not optional. Many common React patterns create inaccessible UIs by default. These rules catch issues early
+- **Trade-off**: May require more verbose markup (explicit labels, ARIA attributes), but creates inclusive applications
+- **When to override**: Rarely. If you must, document why the pattern is accessible despite the warning
+
+**Modern JSX Transform**: Configured for React 17+ (no `React` import needed)
+
+- **Why**: The new JSX transform is more efficient and doesn't require importing React in every file. It's the modern standard
+- **Trade-off**: None - this is the recommended approach for React 17+
+- **When to override**: If stuck on React 16 or earlier (but you should upgrade)
+
+**Component Display Names**: Enforces display names for debugging
+
+- **Why**: Display names improve debugging in React DevTools and error messages. Anonymous components are harder to track down
+- **Trade-off**: Requires naming arrow function components or adding explicit displayName
+- **When to override**: For simple, obvious components where the name is clear from context (rare)
+
+**Extends Base TypeScript Config**: Inherits all strict type checking rules
+
+- **Why**: React components benefit from strict typing. Props, state, and event handlers should all be explicitly typed
+- **Trade-off**: More verbose component definitions, but prevents prop drilling bugs and refactoring issues
+- **When to override**: Follow the same guidelines as the base TypeScript config
+
 ## 🎯 When to Use
 
 Use this configuration when you want:
@@ -213,8 +251,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
@@ -319,7 +357,7 @@ useEffect(() => {
 Ensure React is installed:
 
 ```bash
-npm install react
+pnpm add react
 ```
 
 Or explicitly specify the React version:
@@ -360,7 +398,7 @@ This config should handle `.tsx` files automatically. If you're having issues:
 2. Verify TypeScript is installed:
 
 ```bash
-npm install --save-dev typescript
+pnpm add -D typescript
 ```
 
 3. Check that your tsconfig.json is in the project root
@@ -378,10 +416,7 @@ npm install --save-dev typescript
 **Solution:**
 
 ```bash
-# Use --legacy-peer-deps during installation
-npm install --legacy-peer-deps
-
-# Or use pnpm which handles peer deps automatically
+# pnpm automatically handles peer dependencies
 pnpm install
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmlweb/eslint-config-react",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "ESLint configuration for React libraries with TypeScript, extending base config with React-specific rules",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -54,10 +54,10 @@
     "eslint-plugin-react-hooks": "^5.0.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",
@@ -70,8 +70,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",