@jmlweb/tsconfig-base 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @jmlweb/tsconfig-base
 
+## 1.0.4
+
+### Patch Changes
+
+- 4a9ece1: Update documentation to use pnpm commands instead of npm
+
+## 1.0.3
+
+### Patch Changes
+
+- 6b73301: Add changelog section with link to CHANGELOG.md in package READMEs
+
 ## 1.0.2
 
 ### Patch Changes

package/README.md

@@ -18,9 +18,11 @@
 ## 📦 Installation
 
 ```bash
-npm install --save-dev @jmlweb/tsconfig-base typescript
+pnpm add -D @jmlweb/tsconfig-base typescript
 ```
 
+> 💡 **Upgrading from a previous version?** See the [Migration Guide](#-migration-guide) for breaking changes and upgrade instructions.
+
 ## 🚀 Quick Start
 
 Create a `tsconfig.json` file in your project root:
@@ -157,6 +159,44 @@ This base config intentionally omits `include` and `exclude` patterns because:
 - ✅ Prevents conflicts with project-specific patterns
 - ✅ More flexible for various project types
 
+## 🤔 Why Use This?
+
+> **Philosophy**: TypeScript should catch bugs at compile time through strict type checking. If it compiles without errors, it should work correctly.
+
+This package provides an opinionated TypeScript configuration that enables all strict flags and additional safety checks. It's designed to prevent common JavaScript pitfalls through TypeScript's type system while remaining flexible enough for any project type.
+
+### Design Decisions
+
+**All Strict Flags Enabled (`strict: true` + extras)**: Enables strict null checks, no implicit any, strict function types, etc.
+
+- **Why**: TypeScript's strict mode catches entire classes of bugs (null/undefined errors, implicit any holes, binding issues). Additional flags like `noUncheckedIndexedAccess` catch even more edge cases
+- **Trade-off**: More initial type errors when adopting, requires explicit null handling. But this prevents runtime crashes
+- **When to override**: For gradual migration from JavaScript (but aim to enable all flags eventually)
+
+**Modern Target (ES2022)**: Compiles to ES2022 with modern JavaScript features
+
+- **Why**: Modern Node.js and browsers support ES2022. Using modern features provides better performance and cleaner output. Let your runtime handle the code
+- **Trade-off**: Requires Node.js 18+ or modern browsers. If targeting older environments, override with `ES2020` or lower
+- **When to override**: When supporting legacy environments (but consider transpiling separately)
+
+**NodeNext Module Resolution**: Uses Node.js ESM resolution algorithm
+
+- **Why**: Matches how Node.js resolves modules in real projects. Prevents module resolution mismatches between TypeScript and runtime
+- **Trade-off**: Requires proper package.json exports and file extensions in imports. But this matches modern JavaScript standards
+- **When to override**: For legacy projects using CommonJS exclusively (but you should migrate to ESM)
+
+**No File Inclusion**: Doesn't specify `include` or `exclude` patterns
+
+- **Why**: Different projects have different structures (src/, lib/, packages/). Config shouldn't impose opinions about project layout
+- **Trade-off**: Must define your own `include`/`exclude` in project tsconfig.json (but you'd do this anyway for custom needs)
+- **When to override**: Never - add include/exclude in your project's tsconfig.json
+
+**Source Maps Enabled**: Generates source maps for debugging
+
+- **Why**: Source maps enable debugging TypeScript source in Node.js and browsers. Essential for production debugging
+- **Trade-off**: Slightly larger build output, but negligible compared to debugging benefits
+- **When to override**: If you're absolutely certain you don't need debugging (rare)
+
 ## 🎯 When to Use
 
 Use this configuration when you want:
@@ -241,10 +281,180 @@ See real-world usage examples:
 
 ## 🔗 Related Packages
 
+### Internal Packages
+
 - [`@jmlweb/eslint-config-base`](../eslint-config-base) - ESLint configuration for TypeScript projects
 - [`@jmlweb/prettier-config-base`](../prettier-config-base) - Prettier configuration
 - [`@jmlweb/tsconfig-react`](../tsconfig-react) - TypeScript configuration for React projects
 
+### External Tools
+
+- [TypeScript](https://www.typescriptlang.org/) - Strongly typed programming language that builds on JavaScript
+- [ts-node](https://typestrong.org/ts-node/) - TypeScript execution engine for Node.js
+- [tsx](https://github.com/privatenumber/tsx) - Fast TypeScript/ESM execution (alternative to ts-node)
+- [ESLint](https://eslint.org/) - Linter for TypeScript (use with @jmlweb/eslint-config-base)
+
+## ⚠️ 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).
+
+### Missing File Extensions Error
+
+**Symptoms:**
+
+- Error: "Relative import paths need explicit file extensions in ECMAScript imports"
+- Import statements like `import { foo } from './bar'` fail
+
+**Cause:**
+
+- This config uses `moduleResolution: "NodeNext"` which follows Node.js ESM rules
+- Node.js requires explicit `.js` extensions in import statements (even for `.ts` files)
+
+**Solution:**
+
+Add `.js` extensions to your imports (TypeScript will resolve to `.ts` files):
+
+```typescript
+// Before
+import { foo } from './bar';
+
+// After
+import { foo } from './bar.js';
+```
+
+Or switch to a bundler-based module resolution:
+
+```json
+{
+  "extends": "@jmlweb/tsconfig-base",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+### Module and ModuleResolution Mismatch
+
+**Symptoms:**
+
+- Error: "Option 'module' must be set to 'NodeNext' when 'moduleResolution' is 'NodeNext'"
+- Type errors related to module resolution
+
+**Cause:**
+
+- Both `module` and `moduleResolution` must be set to compatible values
+- This config uses `NodeNext` for both
+
+**Solution:**
+
+If you need to override the module system, update both options together:
+
+```json
+{
+  "extends": "@jmlweb/tsconfig-base",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+### CommonJS vs ESM Mismatch
+
+**Symptoms:**
+
+- Code runs but module resolution is incorrect
+- `require` statements in output when you expected `import`
+
+**Cause:**
+
+- Your `package.json` has `"type": "module"` but your build uses CommonJS
+- Or vice versa
+
+**Solution:**
+
+Match your `package.json` to your build output:
+
+```json
+// package.json
+{
+  "type": "module" // For ESM output (this config's default)
+}
+```
+
+Or override to CommonJS:
+
+```json
+// tsconfig.json
+{
+  "extends": "@jmlweb/tsconfig-base",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "node"
+  }
+}
+```
+
+### Index Signature Type Errors
+
+**Symptoms:**
+
+- Error: "Object is possibly 'undefined'" when accessing object properties
+- Example: `obj[key]` shows type `T | undefined`
+
+**Cause:**
+
+- This config enables `noUncheckedIndexedAccess` for extra safety
+- TypeScript correctly adds `undefined` to index access types
+
+**Solution:**
+
+Use optional chaining or explicit checks:
+
+```typescript
+// Before
+const value = obj[key].toString();
+
+// After - option 1: optional chaining
+const value = obj[key]?.toString();
+
+// After - option 2: explicit check
+if (obj[key] !== undefined) {
+  const value = obj[key].toString();
+}
+
+// After - option 3: type assertion (use sparingly)
+const value = obj[key]!.toString();
+```
+
+Or disable this strict check:
+
+```json
+{
+  "extends": "@jmlweb/tsconfig-base",
+  "compilerOptions": {
+    "noUncheckedIndexedAccess": false
+  }
+}
+```
+
+## 🔄 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/tsconfig-base",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Base TypeScript configuration with strict type checking and modern defaults",
   "main": "tsconfig.json",
   "exports": {