@jmlweb/vitest-config 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @jmlweb/vitest-config
 
+## 1.0.7
+
+### Patch Changes
+
+- 30f8ffb: Add "Why Use This?" sections to package READMEs explaining configuration philosophy and design decisions
+
+## 1.0.6
+
+### Patch Changes
+
+- 4a9ece1: Update documentation to use pnpm commands instead of npm
+
 ## 1.0.5
 
 ### Patch Changes

package/README.md

@@ -19,7 +19,7 @@
 ## 📦 Installation
 
 ```bash
-npm install --save-dev @jmlweb/vitest-config vitest
+pnpm add -D @jmlweb/vitest-config vitest
 ```
 
 > 💡 **Upgrading from a previous version?** See the [Migration Guide](#-migration-guide) for breaking changes and upgrade instructions.
@@ -122,6 +122,38 @@ export default defineConfig({
 });
 ```
 
+## 🤔 Why Use This?
+
+> **Philosophy**: Modern testing should be fast, have excellent DX, and enforce meaningful coverage without slowing down development.
+
+This package provides a Vitest configuration optimized for speed and developer experience while maintaining high code quality standards. It leverages Vitest's Vite-powered architecture for extremely fast test execution and hot module replacement during test development.
+
+### Design Decisions
+
+**80% Coverage Thresholds**: Balanced quality enforcement
+
+- **Why**: 80% coverage ensures most code is tested without creating unrealistic goals that lead to testing trivial code just to hit metrics. It's high enough to catch bugs but low enough to remain practical for real-world development
+- **Trade-off**: Some projects need higher (90%+) or lower (60%) thresholds depending on criticality
+- **When to override**: Increase for safety-critical code, decrease for rapid prototyping or legacy code being brought under test
+
+**Global Test Functions (`globals: true`)**: Familiar testing API
+
+- **Why**: Enables the familiar `describe`, `it`, `expect` globals without imports, matching Jest's API. This makes migration easier and reduces boilerplate in every test file. Most developers expect this API
+- **Trade-off**: Technically pollutes global scope, but this is standard in testing and expected behavior
+- **When to override**: If you prefer explicit imports (`import { describe, it, expect } from 'vitest'`) for stricter code style
+
+**Thread Pool (`pool: 'threads'`)**: Parallel test execution
+
+- **Why**: Vitest's thread pool runs tests in parallel using worker threads, dramatically speeding up large test suites. Much faster than Jest's default process-based isolation while maintaining proper isolation
+- **Trade-off**: Minimal memory overhead from worker threads. But the speed improvement is significant
+- **When to override**: For tests with native modules that don't work in workers - use `forks` pool instead
+
+**V8 Coverage Provider**: Fast native coverage
+
+- **Why**: V8's built-in coverage is significantly faster than instrumentation-based coverage (like Istanbul). For Vitest projects, it's the best choice for speed while maintaining accuracy
+- **Trade-off**: Less configurable than Istanbul, but coverage accuracy is equivalent for modern code
+- **When to override**: Rarely needed - V8 coverage works well for all modern JavaScript/TypeScript
+
 ## 📋 Configuration Details
 
 ### Default Settings
@@ -223,11 +255,11 @@ Add test scripts to your `package.json`:
 Then run:
 
 ```bash
-npm run test           # Run tests in watch mode
-npm run test:run       # Run tests once
-npm run test:coverage # Run tests with coverage
-npm run test:ui       # Open Vitest UI
-npm run test:typecheck # Run TypeScript type checking
+pnpm test           # Run tests in watch mode
+pnpm test:run       # Run tests once
+pnpm test:coverage  # Run tests with coverage
+pnpm test:ui        # Open Vitest UI
+pnpm test:typecheck # Run TypeScript type checking
 ```
 
 ### TypeScript Type Checking
@@ -236,10 +268,10 @@ Type checking is performed separately using the `vitest typecheck` command for b
 
 ```bash
 # Run type checking only
-npm run test:typecheck
+pnpm test:typecheck
 
 # Or run tests and type checking together
-npm run test && npm run test:typecheck
+pnpm test && pnpm test:typecheck
 ```
 
 ## 📋 Requirements
@@ -331,10 +363,10 @@ Install the DOM environment package:
 
 ```bash
 # For jsdom (more compatible, slower)
-npm install --save-dev jsdom
+pnpm add -D jsdom
 
 # Or for happy-dom (faster, less compatible)
-npm install --save-dev happy-dom
+pnpm add -D happy-dom
 ```
 
 Then specify in your config if different from default:
@@ -370,7 +402,7 @@ export default defineConfig({
 Install the coverage provider:
 
 ```bash
-npm install --save-dev @vitest/coverage-v8
+pnpm add -D @vitest/coverage-v8
 ```
 
 Run tests with coverage flag:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmlweb/vitest-config",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Base Vitest configuration for jmlweb projects with TypeScript support and coverage settings",
   "type": "module",
   "main": "./dist/index.cjs",