@jmlweb/tsconfig-astro 1.1.2 → 1.1.4

package/CHANGELOG.md

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

package/README.md

@@ -20,9 +20,11 @@
 ## 📦 Installation
 
 ```bash
-npm install --save-dev @jmlweb/tsconfig-astro typescript astro @jmlweb/tsconfig-base
+pnpm add -D @jmlweb/tsconfig-astro typescript astro @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 Astro project root:
@@ -92,6 +94,38 @@ Create a `tsconfig.json` file in your Astro project root:
 }
 ```
 
+## 🤔 Why Use This?
+
+> **Philosophy**: Astro projects need TypeScript configured to preserve JSX for Astro's compiler while supporting framework components in islands.
+
+This package provides a TypeScript configuration specifically for Astro projects. It extends the strict base configuration while setting up JSX in preserve mode, allowing Astro's compiler to handle the transformation while maintaining full type safety for both Astro components and framework components used in islands.
+
+### Design Decisions
+
+**JSX Preserve Mode (`jsx: "preserve"`)**: Let Astro handle JSX transformation
+
+- **Why**: Astro has its own JSX/TSX transformation pipeline that's optimized for its component model and islands architecture. Preserve mode tells TypeScript to check types but leave the JSX syntax untouched for Astro to process. This enables proper handling of both .astro components and framework components (React, Vue, etc.) in islands
+- **Trade-off**: Can't run TypeScript output directly without Astro's build step. But Astro projects always use Astro's build system anyway
+- **When to override**: Never for Astro projects - Astro requires preserve mode to function correctly
+
+**Bundler Module Resolution (`moduleResolution: "bundler"`)**: Optimized for Vite
+
+- **Why**: Astro uses Vite as its build tool. Bundler resolution is specifically designed for Vite and other modern bundlers, providing better module resolution that matches how Vite actually resolves imports. This prevents TypeScript/runtime mismatches
+- **Trade-off**: Not suitable for direct Node.js execution. But Astro projects always use Vite for building
+- **When to override**: Never for Astro - bundler resolution is optimal for Vite-based frameworks
+
+**DOM Type Definitions (`lib: ["ES2022", "DOM", "DOM.Iterable"]`)**: Browser API support
+
+- **Why**: Astro generates static sites and SPAs that run in browsers. Your components interact with browser APIs through client-side scripts and framework islands. DOM types are essential for type-safe browser API usage
+- **Trade-off**: Includes browser types even for static content. But most Astro sites have some client-side interactivity
+- **When to override**: For purely static sites with zero client-side JavaScript (rare in practice)
+
+**ESNext Modules (`module: "ESNext"`)**: Modern module syntax for Vite
+
+- **Why**: Vite works best with ESNext modules and handles all transpilation to the target environment. Using ESNext modules enables Vite's advanced optimizations like dependency pre-bundling and fast HMR
+- **Trade-off**: TypeScript output isn't directly executable. But Astro handles the build
+- **When to override**: Never for Astro projects - let Vite handle module transformation
+
 ## 📋 Configuration Details
 
 ### What's Included
@@ -227,10 +261,35 @@ This package requires the following peer dependencies:
 
 ## 🔗 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-astro`](../eslint-config-astro) - ESLint configuration for Astro 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
+- [Astro](https://astro.build/) - The web framework for content-driven websites
+- [Astro integrations](https://astro.build/integrations/) - Official and community integrations
+- [Vite](https://vite.dev/) - Build tool used by Astro
+
+## 🔄 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-astro",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "TypeScript configuration for Astro projects with JSX support and modern defaults",
   "main": "tsconfig.json",
   "exports": {
@@ -37,7 +37,7 @@
   "peerDependencies": {
     "astro": ">=4.0.0",
     "typescript": ">=5.0.0",
-    "@jmlweb/tsconfig-base": "1.0.2"
+    "@jmlweb/tsconfig-base": "1.0.4"
   },
   "scripts": {}
 }