@jmlweb/eslint-config-base 2.0.2 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @jmlweb/eslint-config-base
 
+## 2.0.3
+
+### Patch Changes
+
+- 6b73301: Add changelog section with link to CHANGELOG.md in package READMEs
+- Updated dependencies [6b73301]
+  - @jmlweb/eslint-config-base-js@1.0.3
+
 ## 2.0.2
 
 ### Patch Changes

package/README.md

@@ -25,6 +25,8 @@
 npm install --save-dev @jmlweb/eslint-config-base eslint @eslint/js typescript-eslint eslint-config-prettier eslint-plugin-simple-import-sort @jmlweb/eslint-config-base-js
 ```
 
+> 💡 **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:
@@ -302,11 +304,148 @@ See real-world usage examples:
 
 ## 🔗 Related Packages
 
+### Internal Packages
+
 - [`@jmlweb/eslint-config-base-js`](../eslint-config-base-js) - JavaScript ESLint config (extended by this package)
 - [`@jmlweb/eslint-config-react`](../eslint-config-react) - ESLint config for React projects
 - [`@jmlweb/prettier-config-base`](../prettier-config-base) - Prettier config for consistent formatting
 - [`@jmlweb/tsconfig-base`](../tsconfig-base) - TypeScript configuration
 
+### External Tools
+
+- [ESLint](https://eslint.org/) - Pluggable linting utility for JavaScript and TypeScript
+- [TypeScript ESLint](https://typescript-eslint.io/) - TypeScript tooling for ESLint
+- [Prettier](https://prettier.io/) - Opinionated code formatter (pairs with eslint-config-prettier)
+- [eslint-plugin-simple-import-sort](https://github.com/lydell/eslint-plugin-simple-import-sort) - Auto-sorts imports
+
+## ⚠️ 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).
+
+### Peer Dependency Warnings
+
+**Symptoms:**
+
+- `npm WARN` messages about unmet peer dependencies during installation
+- Messages like "requires a peer of eslint@^8.0.0 but none is installed"
+
+**Cause:**
+
+- Some ESLint plugins haven't updated their peer dependencies to support ESLint 9.x
+- This is a transitional issue as the ecosystem adapts to ESLint's flat config
+
+**Solution:**
+
+```bash
+# Use --legacy-peer-deps flag during installation
+npm install --legacy-peer-deps
+
+# Or with pnpm (automatically handles peer dependencies)
+pnpm install
+```
+
+The warnings are usually safe to ignore if your linting works correctly. The plugins typically work fine with ESLint 9.x despite the warnings.
+
+### ESLint Not Picking Up Configuration
+
+**Symptoms:**
+
+- ESLint rules not being applied
+- IDE showing no linting errors
+- Files outside `src/` directory not being linted
+
+**Cause:**
+
+- Missing TypeScript project service configuration
+- `tsconfig.json` not in the correct location
+- IDE ESLint extension not configured for flat config
+
+**Solution:**
+
+1. Ensure your `tsconfig.json` is in your project root
+2. Verify your `eslint.config.js` is using flat config format
+3. For VS Code, update `.vscode/settings.json`:
+
+```json
+{
+  "eslint.experimental.useFlatConfig": true
+}
+```
+
+4. Restart your IDE/ESLint server
+
+### Type-Aware Linting Not Working
+
+**Symptoms:**
+
+- Type-aware rules like `@typescript-eslint/no-unnecessary-condition` not triggering
+- "Parsing error: Cannot read file" messages
+
+**Cause:**
+
+- TypeScript project service not finding your `tsconfig.json`
+- Multiple `tsconfig.json` files causing confusion
+
+**Solution:**
+
+Check your project structure:
+
+```bash
+# Your tsconfig.json should be in the root
+project/
+├── tsconfig.json
+├── eslint.config.js
+└── src/
+```
+
+If you have multiple tsconfig files, this config uses TypeScript project service which automatically detects them.
+
+### Conflicts with Prettier
+
+**Symptoms:**
+
+- ESLint auto-fix and Prettier format fighting each other
+- Code gets reformatted back and forth
+
+**Cause:**
+
+- ESLint formatting rules conflicting with Prettier
+- Running both tools without proper integration
+
+**Solution:**
+
+This config already includes `eslint-config-prettier` to disable conflicting rules. Ensure you:
+
+1. Run Prettier before ESLint:
+
+```json
+{
+  "scripts": {
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "check": "prettier --check . && eslint ."
+  }
+}
+```
+
+2. Configure your IDE to format with Prettier first, then lint with ESLint
+
+## 🔄 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-base",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Base ESLint configuration for TypeScript projects with strict type checking and best practices",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -53,7 +53,7 @@
     "typescript-eslint": "^8.0.0"
   },
   "dependencies": {
-    "@jmlweb/eslint-config-base-js": "1.0.2"
+    "@jmlweb/eslint-config-base-js": "1.0.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",