@jmlweb/tsconfig-node 1.0.3 → 1.0.5

package/CHANGELOG.md

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

package/README.md

@@ -18,9 +18,11 @@
 ## 📦 Installation
 
 ```bash
-npm install --save-dev @jmlweb/tsconfig-node typescript @jmlweb/tsconfig-base
+pnpm add -D @jmlweb/tsconfig-node typescript @jmlweb/tsconfig-base
 ```
 
+> 💡 **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:
@@ -101,6 +103,32 @@ Create a `tsconfig.json` file in your project root:
 }
 ```
 
+## 🤔 Why Use This?
+
+> **Philosophy**: Node.js projects should use only Node.js and ES types, avoiding browser APIs that don't exist in the runtime.
+
+This package provides a TypeScript configuration specifically for Node.js server-side development and CLI tools. It extends the strict base configuration while carefully excluding browser/DOM types that would allow you to accidentally use APIs that don't exist in Node.js.
+
+### Design Decisions
+
+**ES-Only Library Types (`lib: ["ES2022"]`)**: Excludes DOM and browser APIs
+
+- **Why**: Node.js doesn't have browser APIs like `window`, `document`, or DOM event types. Including DOM types in a Node.js project allows you to accidentally write code that compiles but crashes at runtime. This config prevents that entire class of bugs
+- **Trade-off**: Must install `@types/node` separately for Node.js-specific types. But you need that anyway for Node.js development
+- **When to override**: If building a universal library that runs in both Node.js and browsers (but consider having separate tsconfigs for each environment)
+
+**NodeNext Module Resolution (`moduleResolution: "NodeNext"`)**: Matches Node.js module behavior
+
+- **Why**: Node.js has specific module resolution rules, especially with ESM. `NodeNext` resolution matches exactly how Node.js resolves modules, preventing mismatches between TypeScript compilation and runtime behavior
+- **Trade-off**: Requires following Node.js ESM rules (explicit file extensions, package.json exports). But these are Node.js requirements anyway
+- **When to override**: For legacy CommonJS-only projects, you might use `node` resolution, but `NodeNext` works for both CommonJS and ESM
+
+**Dual Module Support**: Works with both CommonJS and ESM
+
+- **Why**: Node.js supports both module systems through package.json `type` field and file extensions. This config respects those conventions, making it work seamlessly whether you're using CommonJS, ESM, or gradually migrating
+- **Trade-off**: Must be deliberate about module format choices in your package.json
+- **When to override**: Never - this flexibility is essential for modern Node.js development
+
 ## 📋 Configuration Details
 
 ### What's Included
@@ -226,7 +254,7 @@ This package requires the following peer dependencies:
 For Node.js projects, you should also install:
 
 ```bash
-npm install --save-dev @types/node
+pnpm add -D @types/node
 ```
 
 This provides Node.js-specific type definitions like `Buffer`, `process`, `fs`, etc.
@@ -239,10 +267,35 @@ See real-world usage examples:
 
 ## 🔗 Related Packages
 
+### Internal Packages
+
 - [`@jmlweb/tsconfig-base`](../tsconfig-base) - Base TypeScript configuration (extended by this package)
-- [`@jmlweb/eslint-config-base`](../eslint-config-base) - ESLint configuration for TypeScript projects
+- [`@jmlweb/eslint-config-node`](../eslint-config-node) - ESLint configuration for Node.js projects
 - [`@jmlweb/prettier-config-base`](../prettier-config-base) - Prettier config for consistent formatting
 
+### External Tools
+
+- [TypeScript](https://www.typescriptlang.org/) - Strongly typed programming language that builds on JavaScript
+- [Node.js](https://nodejs.org/) - JavaScript runtime built on Chrome's V8 engine
+- [tsx](https://github.com/privatenumber/tsx) - TypeScript execute (ts-node alternative)
+- [ts-node](https://typestrong.org/ts-node/) - TypeScript execution engine for Node.js
+
+## 🔄 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-node",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "TypeScript configuration for Node.js and CLI projects. Extends @jmlweb/tsconfig-base with Node.js-specific settings excluding DOM types.",
   "main": "tsconfig.json",
   "exports": {
@@ -37,7 +37,7 @@
   },
   "peerDependencies": {
     "typescript": ">=5.0.0",
-    "@jmlweb/tsconfig-base": "1.0.2"
+    "@jmlweb/tsconfig-base": "1.0.4"
   },
   "scripts": {}
 }