vitest

> Base Vitest configuration for jmlweb projects. TypeScript support, coverage settings, and sensible defaults out of the box.

✨ Features

• 🔧 TypeScript Support: Configured for TypeScript projects (type checking via CLI)
• 📊 Coverage Configuration: Pre-configured with v8 provider and 80% coverage thresholds
• 🎯 Sensible Defaults: Node.js environment, globals enabled, optimized test execution
• ⚡ Performance Optimized: Thread pool configuration for efficient parallel test execution
• 🚀 Easy Extension: Flat config format for easy customization
• 📦 Zero Config: Works out of the box with minimal setup

📦 Installation

pnpm add -D @jmlweb/vitest-config vitest

> 💡 Upgrading from a previous version? See the Migration Guide for breaking changes and upgrade instructions.

🚀 Quick Start

Create a vitest.config.ts file in your project root:

import { defineConfig } from 'vitest/config';
import baseConfig from '@jmlweb/vitest-config';

export default defineConfig({
  ...baseConfig,
  // Add your project-specific overrides here
});

💡 Examples

Basic Setup

vitest.config.ts

import { defineConfig } from 'vitest/config';
import baseConfig from '@jmlweb/vitest-config';

export default defineConfig({
  ...baseConfig,
});

With Project-Specific Overrides

vitest.config.ts

import { defineConfig } from 'vitest/config';
import baseConfig from '@jmlweb/vitest-config';

export default defineConfig({
  ...baseConfig,
  test: {
    ...baseConfig.test,
    // Override environment for browser testing
    environment: 'jsdom',
    // Custom test timeout
    testTimeout: 10000,
    // Custom coverage thresholds
    coverage: {
      ...baseConfig.test?.coverage,
      thresholds: {
        lines: 90,
        functions: 90,
        branches: 85,
        statements: 90,
      },
    },
  },
});

React/JSX Project Example

vitest.config.ts

import { defineConfig } from 'vitest/config';
import baseConfig from '@jmlweb/vitest-config';

export default defineConfig({
  ...baseConfig,
  test: {
    ...baseConfig.test,
    environment: 'jsdom', // Use jsdom for React component testing
    setupFiles: ['./src/test/setup.ts'], // Optional setup file
  },
});

Lower Coverage Thresholds

vitest.config.ts

import { defineConfig } from 'vitest/config';
import baseConfig from '@jmlweb/vitest-config';

export default defineConfig({
  ...baseConfig,
  test: {
    ...baseConfig.test,
    coverage: {
      ...baseConfig.test?.coverage,
      thresholds: {
        lines: 60,
        functions: 60,
        branches: 60,
        statements: 60,
      },
    },
  },
});

🤔 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

Setting	Value	Description
globals	true	Enables global test functions (describe, it, expect)
environment	node	Node.js environment by default
testTimeout	5000	Test timeout in milliseconds (5 seconds)
hookTimeout	10000	Hook timeout in milliseconds (10 seconds)
pool	threads	Use thread pool for parallel test execution
coverage.provider	v8	Coverage provider
coverage.thresholds.lines	80	Minimum line coverage
coverage.thresholds.functions	80	Minimum function coverage
coverage.thresholds.branches	80	Minimum branch coverage
coverage.thresholds.statements	80	Minimum statement coverage

Coverage Exclusions

The following patterns are excluded from coverage by default:

• **/*.d.ts - TypeScript declaration files
• **/*.config.{ts,js} - Configuration files
• **/dist/** - Build output
• **/build/** - Build directories
• **/node_modules/** - Dependencies
• **/coverage/** - Coverage reports
• **/*.test.{ts,tsx,js,jsx} - Test files
• **/*.spec.{ts,tsx,js,jsx} - Spec files

Test File Patterns

Tests are automatically discovered from:

• **/*.test.{ts,tsx,js,jsx}
• **/*.spec.{ts,tsx,js,jsx}

Reporters

Test Reporters:

• verbose - Detailed test output with full test names and results

Coverage Reporters:

• text - Text summary in terminal
• json - JSON format for CI/CD integration
• html - HTML coverage report (generated in coverage/ directory)

🎯 When to Use

Use this configuration when you want:

• ✅ Consistent testing setup across projects
• ✅ TypeScript support out of the box
• ✅ Coverage thresholds enforced
• ✅ Optimized test execution with thread pool
• ✅ Sensible defaults for Node.js projects
• ✅ Easy customization and extension

🔧 Extending the Configuration

You can extend or override the configuration for your specific needs:

import { defineConfig } from 'vitest/config';
import baseConfig from '@jmlweb/vitest-config';

export default defineConfig({
  ...baseConfig,
  test: {
    ...baseConfig.test,
    // Add custom setup files
    setupFiles: ['./src/test/setup.ts'],
    // Custom test patterns
    include: ['**/*.test.ts', '**/__tests__/**/*.ts'],
    // Custom environment
    environment: 'jsdom',
  },
});

📝 Usage with Scripts

Add test scripts to your package.json:

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage",
    "test:ui": "vitest --ui",
    "test:typecheck": "vitest typecheck"
  }
}

Then run:

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

Type checking is performed separately using the vitest typecheck command for better performance. This allows you to run type checking independently of your test suite:

# Run type checking only
pnpm test:typecheck

# Or run tests and type checking together
pnpm test && pnpm test:typecheck

📋 Requirements

• Node.js >= 18.0.0
• Vitest >= 1.0.0
• TypeScript project (recommended, but not required)

📦 Peer Dependencies

This package requires the following peer dependency:

• vitest (^1.0.0)

📚 Examples

See real-world usage examples:

• example-nodejs-typescript-api - Node.js TypeScript API with testing
• example-react-typescript-app - React TypeScript app with component testing

🔗 Related Packages

Internal Packages

• @jmlweb/jest-config - Jest configuration (alternative test runner)
• @jmlweb/eslint-config-base - ESLint config for TypeScript projects
• @jmlweb/prettier-config-base - Prettier config for consistent formatting
• @jmlweb/tsconfig-base - TypeScript configuration

External Tools

• Vitest - Blazing-fast unit test framework powered by Vite
• @testing-library/jest-dom - Custom matchers for the DOM (works with Vitest)
• @testing-library/react - React testing utilities (for React projects)
• @vitest/ui - 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.

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:

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:

# 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:

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:

pnpm add -D @vitest/coverage-v8

Run tests with coverage flag:

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:

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.

Need Help? If you encounter issues during migration, please open an issue.

📜 Changelog

See CHANGELOG.md for version history and release notes.

📄 License

MIT