1---
2name: vitest-configuration
3description: Configure Vitest with vite.config.ts or vitest.config.ts
4---
5 
6# Configuration
7 
8Vitest reads configuration from `vitest.config.ts` or `vite.config.ts`. It shares the same config format as Vite.
9 
10## Basic Setup
11 
12```ts
13// vitest.config.ts
14import { defineConfig } from 'vitest/config'
15 
16export default defineConfig({
17  test: {
18    // test options
19  },
20})
21```
22 
23## Using with Existing Vite Config
24 
25Add Vitest types reference and use the `test` property:
26 
27```ts
28// vite.config.ts
29/// <reference types="vitest/config" />
30import { defineConfig } from 'vite'
31 
32export default defineConfig({
33  test: {
34    globals: true,
35    environment: 'jsdom',
36  },
37})
38```
39 
40## Merging Configs
41 
42If you have separate config files, use `mergeConfig`:
43 
44```ts
45// vitest.config.ts
46import { defineConfig, mergeConfig } from 'vitest/config'
47import viteConfig from './vite.config'
48 
49export default mergeConfig(viteConfig, defineConfig({
50  test: {
51    environment: 'jsdom',
52  },
53}))
54```
55 
56## Common Options
57 
58```ts
59defineConfig({
60  test: {
61    // Enable global APIs (describe, it, expect) without imports
62    globals: true,
63    
64    // Test environment: 'node', 'jsdom', 'happy-dom'
65    environment: 'node',
66    
67    // Setup files to run before each test file
68    setupFiles: ['./tests/setup.ts'],
69    
70    // Include patterns for test files
71    include: ['**/*.{test,spec}.{js,ts,jsx,tsx}'],
72    
73    // Exclude patterns
74    exclude: ['**/node_modules/**', '**/dist/**'],
75    
76    // Test timeout in ms
77    testTimeout: 5000,
78    
79    // Hook timeout in ms
80    hookTimeout: 10000,
81    
82    // Enable watch mode by default
83    watch: true,
84    
85    // Coverage configuration
86    coverage: {
87      provider: 'v8', // or 'istanbul'
88      reporter: ['text', 'html'],
89      include: ['src/**/*.ts'],
90    },
91    
92    // Run tests in isolation (each file in separate process)
93    isolate: true,
94    
95    // Pool for running tests: 'threads', 'forks', 'vmThreads'
96    pool: 'threads',
97    
98    // Number of threads/processes
99    poolOptions: {
100      threads: {
101        maxThreads: 4,
102        minThreads: 1,
103      },
104    },
105    
106    // Automatically clear mocks between tests
107    clearMocks: true,
108    
109    // Restore mocks between tests
110    restoreMocks: true,
111    
112    // Retry failed tests
113    retry: 0,
114    
115    // Stop after first failure
116    bail: 0,
117  },
118})
119```
120 
121## Conditional Configuration
122 
123Use `mode` or `process.env.VITEST` for test-specific config:
124 
125```ts
126export default defineConfig(({ mode }) => ({
127  plugins: mode === 'test' ? [] : [myPlugin()],
128  test: {
129    // test options
130  },
131}))
132```
133 
134## Projects (Monorepos)
135 
136Run different configurations in the same Vitest process:
137 
138```ts
139defineConfig({
140  test: {
141    projects: [
142      'packages/*',
143      {
144        test: {
145          name: 'unit',
146          include: ['tests/unit/**/*.test.ts'],
147          environment: 'node',
148        },
149      },
150      {
151        test: {
152          name: 'integration',
153          include: ['tests/integration/**/*.test.ts'],
154          environment: 'jsdom',
155        },
156      },
157    ],
158  },
159})
160```
161 
162## Key Points
163 
164- Vitest uses Vite's transformation pipeline - same `resolve.alias`, plugins work
165- `vitest.config.ts` takes priority over `vite.config.ts`
166- Use `--config` flag to specify a custom config path
167- `process.env.VITEST` is set to `true` when running tests
168- Test config uses `test` property, rest is Vite config
169 
170<!-- 
171Source references:
172- https://vitest.dev/guide/#configuring-vitest
173- https://vitest.dev/config/
174-->
175