@jmlweb/eslint-config-base 2.0.2 → 2.0.4

package/CHANGELOG.md

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

@@ -22,9 +22,11 @@
 ## 📦 Installation
 
 ```bash
-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
+pnpm add -D @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:
@@ -215,9 +217,59 @@ import { Component } from './component';
 Fix import order automatically:
 
 ```bash
-npx eslint --fix .
+pnpm exec eslint --fix .
 ```
 
+## 🤔 Why Use This?
+
+> **Philosophy**: Maximize type safety. Catch bugs at compile time, not runtime. Make invalid states unrepresentable.
+
+This package enforces strict TypeScript practices inspired by the principle that "if it compiles, it works." The configuration choices reflect a philosophy of using TypeScript's type system to its fullest potential to prevent bugs before they happen.
+
+### Design Decisions
+
+**Strict Type Checking (`strictTypeChecked`)**: Enables all strict type-aware rules
+
+- **Why**: TypeScript's power comes from its type system. Strict checking catches errors like unreachable code, unnecessary conditions, and type mismatches that would otherwise cause runtime bugs
+- **Trade-off**: More initial errors when adopting this config, and requires explicit typing. However, the bugs caught far outweigh the extra effort
+- **When to override**: If migrating a large JavaScript codebase and need a gradual transition (consider using `@jmlweb/eslint-config-base-js` with recommended TypeScript rules instead)
+
+**Explicit Return Types (`@typescript-eslint/explicit-function-return-type`)**: Requires explicit return types on functions
+
+- **Why**: Explicit return types prevent accidental type changes and make code easier to reason about. They serve as inline documentation and catch errors where functions return unexpected types
+- **Trade-off**: More verbose code, but improved clarity and safety. Inference can hide bugs
+- **When to override**: For simple, obvious functions where the return type is trivial (but be conservative - explicit is usually better)
+
+**No `any` Type (`@typescript-eslint/no-explicit-any`)**: Prohibits using `any`
+
+- **Why**: `any` defeats the purpose of TypeScript by disabling type checking. It's a common escape hatch that creates type holes and runtime bugs
+- **Trade-off**: Forces you to properly type external libraries or complex types. Requires more upfront work but prevents bugs
+- **When to override**: Only when dealing with truly dynamic data that can't be typed (rare). Consider `unknown` first
+
+**Type-Only Imports (`@typescript-eslint/consistent-type-imports`)**: Enforces `import type` for type-only imports
+
+- **Why**: Separates runtime imports from type imports, improving tree-shaking and build performance. Makes it clear what's used at runtime vs. compile time
+- **Trade-off**: More explicit imports, but clearer code and better build optimization
+- **When to override**: Never - this is a best practice with no real downsides
+
+**No Enums (`no-restricted-syntax`)**: Prevents TypeScript enum usage
+
+- **Why**: TypeScript enums have surprising runtime behavior, bundling issues, and const vs. regular enum confusion. Const maps with `as const` provide the same benefits without the pitfalls
+- **Trade-off**: Slightly more verbose syntax (`const Status = { ... } as const`), but more predictable and type-safe
+- **When to override**: If you're comfortable with enum limitations or maintaining legacy code
+
+**No Default Exports (`no-restricted-exports`)**: Enforces named exports only
+
+- **Why**: Named exports enable better tree-shaking, clearer imports, easier refactoring, and better IDE autocomplete. Default exports hide what's being imported
+- **Trade-off**: Can't use `import Foo from './foo'` syntax. Requires `import { Foo } from './foo'`
+- **When to override**: For compatibility with libraries that require default exports (Next.js pages, etc.) - override per-file
+
+**Naming Conventions (`@typescript-eslint/naming-convention`)**: Enforces consistent naming patterns
+
+- **Why**: Consistent naming improves readability and prevents bugs. For example, booleans starting with `is/has/can` are self-documenting
+- **Trade-off**: May conflict with legacy code or third-party APIs
+- **When to override**: When integrating with external APIs that use different conventions
+
 ## 🎯 When to Use
 
 Use this configuration when you want:
@@ -272,8 +324,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
@@ -302,11 +354,145 @@ 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
+# 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.4",
   "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.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",