@jmlweb/eslint-config-react 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @jmlweb/eslint-config-react
 
+## 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
+
+- 6b73301: Add changelog section with link to CHANGELOG.md in package READMEs
+- Updated dependencies [6b73301]
+  - @jmlweb/eslint-config-base@2.0.3
+
 ## 2.0.3
 
 ### Patch Changes

package/README.md

@@ -23,9 +23,11 @@
 ## 📦 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.
+
 ## 🚀 Quick Start
 
 Create an `eslint.config.js` file in your project root:
@@ -154,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:
@@ -211,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
@@ -244,10 +284,160 @@ See real-world usage examples:
 
 ## 🔗 Related Packages
 
+### Internal Packages
+
 - [`@jmlweb/eslint-config-base`](../eslint-config-base) - Base TypeScript ESLint config (extended by this package)
 - [`@jmlweb/tsconfig-react`](../tsconfig-react) - TypeScript configuration for React libraries
 - [`@jmlweb/prettier-config-base`](../prettier-config-base) - Prettier config for consistent formatting
 
+### External Tools
+
+- [ESLint](https://eslint.org/) - Pluggable linting utility for JavaScript and TypeScript
+- [TypeScript ESLint](https://typescript-eslint.io/) - TypeScript tooling for ESLint
+- [React](https://react.dev/) - JavaScript library for building user interfaces
+- [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) - React-specific linting rules
+- [eslint-plugin-react-hooks](https://www.npmjs.com/package/eslint-plugin-react-hooks) - Enforces Rules of Hooks
+- [Prettier](https://prettier.io/) - Opinionated code formatter
+
+## ⚠️ Common Issues
+
+> **Note:** This section documents known issues and their solutions. If you encounter a problem not listed here, please [open an issue](https://github.com/jmlweb/tooling/issues/new).
+
+### React Hooks Exhaustive Dependencies Warning
+
+**Symptoms:**
+
+- Warning: "React Hook useEffect has a missing dependency"
+- ESLint suggests adding dependencies to the dependency array
+
+**Cause:**
+
+- `eslint-plugin-react-hooks` enforces the Rules of Hooks
+- Missing dependencies can cause stale closures and bugs
+
+**Solution:**
+
+Add the missing dependencies:
+
+```typescript
+// Before
+useEffect(() => {
+  fetchData(userId);
+}, []); // Missing dependency: userId
+
+// After
+useEffect(() => {
+  fetchData(userId);
+}, [userId]); // Include all dependencies
+```
+
+If you intentionally want to omit a dependency (use sparingly):
+
+```typescript
+useEffect(() => {
+  fetchData(userId);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+}, []); // Explicitly disable the rule with a comment
+```
+
+### React Version Not Detected
+
+**Symptoms:**
+
+- Warning: "Warning: React version not specified in eslint-plugin-react settings"
+- Or incorrect React version being used
+
+**Cause:**
+
+- This config uses `detect` to auto-detect React version from package.json
+- May fail if React is not installed or in an unexpected location
+
+**Solution:**
+
+Ensure React is installed:
+
+```bash
+pnpm add react
+```
+
+Or explicitly specify the React version:
+
+```javascript
+// eslint.config.js
+import reactConfig from '@jmlweb/eslint-config-react';
+
+export default [
+  ...reactConfig,
+  {
+    settings: {
+      react: {
+        version: '18.2', // Specify your React version
+      },
+    },
+  },
+];
+```
+
+### JSX Not Recognized in .tsx Files
+
+**Symptoms:**
+
+- Parsing errors in `.tsx` files with JSX
+- "Unexpected token <" errors
+
+**Cause:**
+
+- TypeScript parser not configured correctly
+- File extension not recognized
+
+**Solution:**
+
+This config should handle `.tsx` files automatically. If you're having issues:
+
+1. Ensure your file has the `.tsx` extension (not `.ts`)
+2. Verify TypeScript is installed:
+
+```bash
+pnpm add -D typescript
+```
+
+3. Check that your tsconfig.json is in the project root
+
+### Peer Dependency Warnings
+
+**Symptoms:**
+
+- npm warnings about unmet peer dependencies for `eslint-plugin-react` or `eslint-plugin-react-hooks`
+
+**Cause:**
+
+- These plugins may not have updated peer dependencies for ESLint 9.x yet
+
+**Solution:**
+
+```bash
+# pnpm automatically handles peer dependencies
+pnpm install
+```
+
+The warnings are usually safe to ignore if linting works correctly.
+
+## 🔄 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](./CHANGELOG.md).
+
+**Need Help?** If you encounter issues during migration, please [open an issue](https://github.com/jmlweb/tooling/issues/new).
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.
+
 ## 📄 License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmlweb/eslint-config-react",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "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.2"
+    "@jmlweb/eslint-config-base": "2.0.4"
   },
   "dependencies": {
-    "@jmlweb/eslint-config-base": "2.0.2"
+    "@jmlweb/eslint-config-base": "2.0.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
@@ -70,7 +70,7 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.34.1",
-    "@jmlweb/eslint-config-base": "2.0.2",
+    "@jmlweb/eslint-config-base": "2.0.4",
     "@jmlweb/tsconfig-internal": "0.0.1"
   },
   "scripts": {