@jmlweb/tsconfig-nextjs 1.1.4 → 1.1.6

package/CHANGELOG.md

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

package/README.md

@@ -21,9 +21,11 @@
 ## 📦 Installation
 
 ```bash
-npm install --save-dev @jmlweb/tsconfig-nextjs typescript next @jmlweb/tsconfig-react @jmlweb/tsconfig-base
+pnpm add -D @jmlweb/tsconfig-nextjs typescript next @jmlweb/tsconfig-react @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 Next.js project root:
@@ -92,6 +94,32 @@ Create a `tsconfig.json` file in your Next.js project root:
 }
 ```
 
+## 🤔 Why Use This?
+
+> **Philosophy**: Next.js projects need TypeScript configured for both server and client code with incremental builds and framework-specific optimizations.
+
+This package provides a TypeScript configuration specifically optimized for Next.js applications. It extends the React configuration while adding Next.js-specific settings like incremental compilation, the Next.js TypeScript plugin, and sensible path aliases that work with Next.js's file-based routing.
+
+### Design Decisions
+
+**Incremental Compilation (`incremental: true`)**: Faster rebuilds for development
+
+- **Why**: Next.js projects are often large with many files. Incremental compilation dramatically speeds up subsequent builds by only recompiling changed files and their dependents. This makes the development experience much faster
+- **Trade-off**: Creates a `.tsbuildinfo` file that needs to be gitignored. But the build speed improvement is worth it
+- **When to override**: Never - there's no downside to incremental compilation in Next.js projects
+
+**Next.js TypeScript Plugin**: Framework-specific type checking
+
+- **Why**: Next.js has special conventions (Server Components, Route Handlers, Metadata API, etc.) that benefit from enhanced type checking. The plugin provides better autocomplete and catches Next.js-specific errors that generic TypeScript can't detect
+- **Trade-off**: Adds a dependency on Next.js being installed. But if you're using this config, you're already using Next.js
+- **When to override**: Only if the plugin causes issues (rare), but report bugs to Next.js if found
+
+**Path Aliases (`@/*` → project root)**: Clean imports for Next.js file structure
+
+- **Why**: Next.js projects have deep file structures (app/components/ui/button/index.tsx). Path aliases like `@/components/ui/button` are more readable and easier to refactor than `../../../components/ui/button`. The `@/*` convention is standard in Next.js projects
+- **Trade-off**: Need to configure the same alias in next.config.js for runtime (though Next.js 13+ does this automatically from tsconfig.json)
+- **When to override**: If your team prefers a different alias convention (like `~/*`), but `@/*` is the Next.js convention
+
 ## 📋 Configuration Details
 
 ### What's Included
@@ -287,11 +315,36 @@ This package requires the following peer dependencies:
 
 ## 🔗 Related Packages
 
+### Internal Packages
+
 - [`@jmlweb/tsconfig-react`](../tsconfig-react) - TypeScript configuration for React (extended by this package)
 - [`@jmlweb/tsconfig-base`](../tsconfig-base) - Base TypeScript configuration
 - [`@jmlweb/eslint-config-react`](../eslint-config-react) - ESLint configuration for React/Next.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
+- [Next.js](https://nextjs.org/) - The React framework for production
+- [React](https://react.dev/) - JavaScript library for building user interfaces
+- [Turbopack](https://turbo.build/pack) - Incremental bundler optimized for JavaScript and TypeScript
+
+## 🔄 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-nextjs",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "TypeScript configuration for Next.js applications with App Router and Pages Router support",
   "main": "tsconfig.json",
   "exports": {
@@ -38,7 +38,7 @@
   "peerDependencies": {
     "next": ">=13.0.0",
     "typescript": ">=5.0.0",
-    "@jmlweb/tsconfig-react": "1.0.3"
+    "@jmlweb/tsconfig-react": "1.0.5"
   },
   "scripts": {}
 }