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    // Limit test discovery to a directory (faster than broad excludes)
77    dir: './src',
78 
79    // Test timeout in ms
80    testTimeout: 5000,
81    
82    // Hook timeout in ms
83    hookTimeout: 10000,
84    
85    // Coverage configuration (v4+: define `include`, no more `all`)
86    coverage: {
87      provider: 'v8', // or 'istanbul'
88      reporter: ['text', 'html'],
89      include: ['src/**/*.ts'],
90    },
91    
92    // Run each file in an isolated module graph (threads/forks pools only)
93    isolate: true,
94    
95    // Pool: 'forks' (default), 'threads', 'vmForks', 'vmThreads'
96    pool: 'forks',
97    
98    // v4+: pool options are top-level (poolOptions was removed)
99    maxWorkers: 4,
100    fileParallelism: true,
101    
102    // Automatically clear mocks between tests
103    clearMocks: true,
104    
105    // Restore spies created with vi.spyOn between tests
106    restoreMocks: true,
107    
108    // Retry failed tests
109    retry: 0,
110    
111    // Stop after first failure
112    bail: 0,
113  },
114})
115```
116 
117## v4/v5 Config Changes
118 
119- **Pool default is `forks`** (child processes), not `threads`.
120- **`poolOptions` removed** — `maxThreads`/`maxForks` are now top-level `maxWorkers`; `singleThread`/`singleFork` become `maxWorkers: 1, isolate: false`; VM `memoryLimit` is `vmMemoryLimit`. `minWorkers` was removed.
121- **`workspace` removed** — use [`projects`](advanced-projects.md). `vitest.workspace.ts` no longer supported.
122- **`coverage.all` and `coverage.extensions` removed** — by default only covered files are reported; set `coverage.include` explicitly.
123- **Simplified `exclude`** — only `node_modules`/`.git` excluded by default. Use `test.dir` to scope discovery, or spread `configDefaults.exclude`.
124- **Config not looked up from parent dirs** — pass `--config` explicitly when running from a subdirectory.
125- **`.vitest` artifact dir** — blob reports (`.vitest/blob/`), attachments (`.vitest/attachments/`), and HTML report now live under a single `.vitest/` directory; add one entry to `.gitignore`.
126- `deps.optimizer.web` renamed to `deps.optimizer.client`; `deps.inline`/`deps.external` moved under `server.deps`.
127 
128## Conditional Configuration
129 
130Use `mode` or `process.env.VITEST` for test-specific config:
131 
132```ts
133export default defineConfig(({ mode }) => ({
134  plugins: mode === 'test' ? [] : [myPlugin()],
135  test: {
136    // test options
137  },
138}))
139```
140 
141## Projects (Monorepos)
142 
143Run different configurations in the same Vitest process:
144 
145```ts
146defineConfig({
147  test: {
148    projects: [
149      'packages/*',
150      {
151        test: {
152          name: 'unit',
153          include: ['tests/unit/**/*.test.ts'],
154          environment: 'node',
155        },
156      },
157      {
158        test: {
159          name: 'integration',
160          include: ['tests/integration/**/*.test.ts'],
161          environment: 'jsdom',
162        },
163      },
164    ],
165  },
166})
167```
168 
169## Key Points
170 
171- Vitest uses Vite's transformation pipeline - same `resolve.alias`, plugins work
172- `vitest.config.ts` takes priority over `vite.config.ts`
173- Use `--config` flag to specify a custom config path (required from subdirectories in v5)
174- `process.env.VITEST` is set to `true` when running tests
175- Test config uses `test` property, rest is Vite config
176- v4 requires **Vite >= 6** and **Node >= 20**; v5 is currently in beta
177 
178<!-- 
179Source references:
180- https://vitest.dev/guide/#configuring-vitest
181- https://vitest.dev/config/
182-->
183