1---
2name: projects-workspaces
3description: Multi-project configuration for monorepos and different test types
4---
5 
6# Projects
7 
8Run different test configurations in the same Vitest process.
9 
10## Basic Projects Setup
11 
12```ts
13// vitest.config.ts
14defineConfig({
15  test: {
16    projects: [
17      // Glob patterns for config files
18      'packages/*',
19      
20      // Inline config
21      {
22        test: {
23          name: 'unit',
24          include: ['tests/unit/**/*.test.ts'],
25          environment: 'node',
26        },
27      },
28      {
29        test: {
30          name: 'integration',
31          include: ['tests/integration/**/*.test.ts'],
32          environment: 'jsdom',
33        },
34      },
35    ],
36  },
37})
38```
39 
40## Monorepo Pattern
41 
42```ts
43defineConfig({
44  test: {
45    projects: [
46      // Each package has its own vitest.config.ts
47      'packages/core',
48      'packages/cli',
49      'packages/utils',
50    ],
51  },
52})
53```
54 
55Package config:
56 
57```ts
58// packages/core/vitest.config.ts
59import { defineConfig } from 'vitest/config'
60 
61export default defineConfig({
62  test: {
63    name: 'core',
64    include: ['src/**/*.test.ts'],
65    environment: 'node',
66  },
67})
68```
69 
70## Different Environments
71 
72Run same tests in different environments:
73 
74```ts
75defineConfig({
76  test: {
77    projects: [
78      {
79        test: {
80          name: 'happy-dom',
81          root: './shared-tests',
82          environment: 'happy-dom',
83          setupFiles: ['./setup.happy-dom.ts'],
84        },
85      },
86      {
87        test: {
88          name: 'node',
89          root: './shared-tests',
90          environment: 'node',
91          setupFiles: ['./setup.node.ts'],
92        },
93      },
94    ],
95  },
96})
97```
98 
99## Browser + Node Projects
100 
101```ts
102defineConfig({
103  test: {
104    projects: [
105      {
106        test: {
107          name: 'unit',
108          include: ['tests/unit/**/*.test.ts'],
109          environment: 'node',
110        },
111      },
112      {
113        test: {
114          name: 'browser',
115          include: ['tests/browser/**/*.test.ts'],
116          browser: {
117            enabled: true,
118            name: 'chromium',
119            provider: 'playwright',
120          },
121        },
122      },
123    ],
124  },
125})
126```
127 
128## Shared Configuration
129 
130```ts
131// vitest.shared.ts
132export const sharedConfig = {
133  testTimeout: 10000,
134  setupFiles: ['./tests/setup.ts'],
135}
136 
137// vitest.config.ts
138import { sharedConfig } from './vitest.shared'
139 
140defineConfig({
141  test: {
142    projects: [
143      {
144        test: {
145          ...sharedConfig,
146          name: 'unit',
147          include: ['tests/unit/**/*.test.ts'],
148        },
149      },
150      {
151        test: {
152          ...sharedConfig,
153          name: 'e2e',
154          include: ['tests/e2e/**/*.test.ts'],
155        },
156      },
157    ],
158  },
159})
160```
161 
162## Project-Specific Dependencies
163 
164Each project can have different dependencies inlined:
165 
166```ts
167defineConfig({
168  test: {
169    projects: [
170      {
171        test: {
172          name: 'project-a',
173          server: {
174            deps: {
175              inline: ['package-a'],
176            },
177          },
178        },
179      },
180    ],
181  },
182})
183```
184 
185## Running Specific Projects
186 
187```bash
188# Run specific project
189vitest --project unit
190vitest --project integration
191 
192# Multiple projects
193vitest --project unit --project e2e
194 
195# Exclude project
196vitest --project.ignore browser
197```
198 
199## Providing Values to Projects
200 
201Share values from config to tests:
202 
203```ts
204// vitest.config.ts
205defineConfig({
206  test: {
207    projects: [
208      {
209        test: {
210          name: 'staging',
211          provide: {
212            apiUrl: 'https://staging.api.com',
213            debug: true,
214          },
215        },
216      },
217      {
218        test: {
219          name: 'production',
220          provide: {
221            apiUrl: 'https://api.com',
222            debug: false,
223          },
224        },
225      },
226    ],
227  },
228})
229 
230// In tests, use inject
231import { inject } from 'vitest'
232 
233test('uses correct api', () => {
234  const url = inject('apiUrl')
235  expect(url).toContain('api.com')
236})
237```
238 
239## With Fixtures
240 
241```ts
242const test = base.extend({
243  apiUrl: ['/default', { injected: true }],
244})
245 
246test('uses injected url', ({ apiUrl }) => {
247  // apiUrl comes from project's provide config
248})
249```
250 
251## Project Isolation
252 
253Each project runs in its own thread pool by default:
254 
255```ts
256defineConfig({
257  test: {
258    projects: [
259      {
260        test: {
261          name: 'isolated',
262          isolate: true, // Full isolation
263          pool: 'forks',
264        },
265      },
266    ],
267  },
268})
269```
270 
271## Global Setup per Project
272 
273```ts
274defineConfig({
275  test: {
276    projects: [
277      {
278        test: {
279          name: 'with-db',
280          globalSetup: ['./tests/db-setup.ts'],
281        },
282      },
283    ],
284  },
285})
286```
287 
288## Key Points
289 
290- Projects run in same Vitest process
291- Each project can have different environment, config
292- Use glob patterns for monorepo packages
293- Run specific projects with `--project` flag
294- Use `provide` to inject config values into tests
295- Projects inherit from root config unless overridden
296 
297<!-- 
298Source references:
299- https://vitest.dev/guide/projects.html
300-->
301