@jmlweb/vitest-config 1.0.4 → 1.0.6

package/CHANGELOG.md

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

package/README.md

@@ -19,9 +19,11 @@
 ## 📦 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.
+
 ## 🚀 Quick Start
 
 Create a `vitest.config.ts` file in your project root:
@@ -120,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
@@ -221,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
@@ -234,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
@@ -261,10 +295,172 @@ See real-world usage examples:
 
 ## 🔗 Related Packages
 
+### Internal Packages
+
+- [`@jmlweb/jest-config`](../jest-config) - Jest configuration (alternative test runner)
 - [`@jmlweb/eslint-config-base`](../eslint-config-base) - ESLint config for TypeScript projects
 - [`@jmlweb/prettier-config-base`](../prettier-config-base) - Prettier config for consistent formatting
 - [`@jmlweb/tsconfig-base`](../tsconfig-base) - TypeScript configuration
 
+### External Tools
+
+- [Vitest](https://vitest.dev/) - Blazing-fast unit test framework powered by Vite
+- [@testing-library/jest-dom](https://testing-library.com/docs/ecosystem-jest-dom/) - Custom matchers for the DOM (works with Vitest)
+- [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) - React testing utilities (for React projects)
+- [@vitest/ui](https://vitest.dev/guide/ui.html) - Visual UI for Vitest test results
+
+## ⚠️ 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).
+
+### Module Resolution Issues
+
+**Symptoms:**
+
+- Error: "Cannot find module" when running tests
+- Import paths work in the app but fail in tests
+
+**Cause:**
+
+- Vitest uses Vite's module resolution which may differ from TypeScript
+- Path aliases or special imports not configured for tests
+
+**Solution:**
+
+If you're using path aliases in `tsconfig.json`, configure them in your Vitest config:
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import vitestConfig from '@jmlweb/vitest-config';
+
+export default defineConfig({
+  ...vitestConfig,
+  resolve: {
+    alias: {
+      '@': '/src',
+      '@components': '/src/components',
+    },
+  },
+});
+```
+
+### jsdom or happy-dom Not Found
+
+**Symptoms:**
+
+- Error: "Environment 'jsdom' not found" or "Environment 'happy-dom' not found"
+- Tests fail to run with DOM-related errors
+
+**Cause:**
+
+- The test environment package is not installed
+- This config specifies the environment but doesn't install it (peer dependency)
+
+**Solution:**
+
+Install the DOM environment package:
+
+```bash
+# For jsdom (more compatible, slower)
+pnpm add -D jsdom
+
+# Or for happy-dom (faster, less compatible)
+pnpm add -D happy-dom
+```
+
+Then specify in your config if different from default:
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import vitestConfig from '@jmlweb/vitest-config';
+
+export default defineConfig({
+  ...vitestConfig,
+  test: {
+    ...vitestConfig.test,
+    environment: 'jsdom', // or 'happy-dom'
+  },
+});
+```
+
+### Coverage Not Working
+
+**Symptoms:**
+
+- No coverage reports generated
+- Coverage command runs but shows no output
+
+**Cause:**
+
+- Coverage provider not installed
+- Coverage not enabled in configuration
+
+**Solution:**
+
+Install the coverage provider:
+
+```bash
+pnpm add -D @vitest/coverage-v8
+```
+
+Run tests with coverage flag:
+
+```bash
+vitest --coverage
+```
+
+### Test Files Not Found
+
+**Symptoms:**
+
+- "No test files found" even though test files exist
+- Vitest doesn't pick up `*.test.ts` or `*.spec.ts` files
+
+**Cause:**
+
+- Test file pattern mismatch
+- Files in excluded directories
+
+**Solution:**
+
+This config includes common patterns. If your tests aren't found, check:
+
+1. File naming: Use `.test.ts`, `.spec.ts`, `.test.tsx`, or `.spec.tsx`
+2. Location: Ensure tests aren't in `node_modules` or `dist`
+3. Explicitly include test patterns:
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import vitestConfig from '@jmlweb/vitest-config';
+
+export default defineConfig({
+  ...vitestConfig,
+  test: {
+    ...vitestConfig.test,
+    include: ['**/*.{test,spec}.{ts,tsx}'],
+  },
+});
+```
+
+## 🔄 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/vitest-config",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Base Vitest configuration for jmlweb projects with TypeScript support and coverage settings",
   "type": "module",
   "main": "./dist/index.cjs",