Vitest 24 🧪 Projects Configuration — Replacing deprecated workspace with projects
As monorepos and multi-package codebases scale, running a single Vitest configuration file across client code, server APIs, and end-to-end integration suites becomes unsustainable. Vitest introduced vitest.workspace.ts to manage multiple test projects under a single runner instance, but modern Vitest versions have officially deprecated the dedicated workspace file in favor of the unified projects configuration property inside vitest.config.ts.
Migrating to the projects property centralizes workspace management, eliminates fragmented config files across nested packages, and allows developers to run client-side DOM tests and backend Node tests simultaneously. This chapter explores configuration migration, project isolation, shared setting inheritance, and multi-project CLI filtering.
Key point: Vitest replaces the deprecated vitest.workspace.ts file with the unified projects array property inside vitest.config.ts, enabling multi-environment test orchestration from a single configuration file.
Why X exists
The fragmented workspace file problem.
Maintaining standalone vitest.workspace.ts or vitest.workspace.js files alongside primary configuration files cluttered repository roots and confused tooling resolution paths.
The environment isolation challenge.
Client-side code running in browser-simulated environments (jsdom or happy-dom) requires different globals, transforms, and setup files than backend server APIs running in a pure Node environment.
The shared configuration duplication problem.
Copying identical setup rules, coverage thresholds, and resolve aliases across multiple standalone package configurations created massive maintenance overhead.
The unified CI orchestration gap.
Continuous integration pipelines needed a streamlined way to discover and execute diverse project environments concurrently without spawning separate CLI processes for each package.
The configuration deprecation drift.
Consolidating workspace semantics into the standard vitest.config.ts file aligns Vitest’s architecture with standard Vite multi-config patterns.
a. Migrating from Workspace Files to the Projects Array
To migrate away from the deprecated workspace pattern, delete your vitest.workspace.ts file and declare your test environments directly inside the projects array property within your root vitest.config.ts.
TypeScript
// vitest.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
// Global defaults shared across all child projects
test: {
globals: true,
coverage: {
provider: 'v8',
},
},
// Unified projects configuration replacing vitest.workspace.ts
projects: [
{
name: 'client-dom',
test: {
environment: 'happy-dom',
include: ['src/client/**/*.test.ts'],
},
},
{
name: 'server-api',
test: {
environment: 'node',
include: ['src/server/**/*.test.ts'],
},
},
],
});
Using the projects array allows Vitest to initialize distinct worker pools for each environment while inheriting root configuration settings automatically.
b. Inheriting Shared Settings and Overriding Environment Globals
Child projects inside the projects array automatically inherit root-level test and resolve configurations. However, individual projects can override specific properties—such as test environments, setup files, or transform rules—to suit targeted runtimes.
TypeScript
// vitest.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
reporters: ['default', 'html'],
poolOptions: {
threads: { singleThread: false },
},
},
projects: [
{
name: 'react-components',
test: {
environment: 'jsdom',
setupFiles: ['./src/test/setup-dom.ts'],
include: ['src/components/**/*.test.tsx'],
},
},
{
name: 'backend-services',
test: {
environment: 'node',
setupFiles: ['./src/test/setup-node.ts'],
include: ['src/services/**/*.test.ts'],
},
},
],
});
This configuration ensures that component tests load browser DOM matchers via setup-dom.ts, while backend services load database connection mocks via setup-node.ts, all managed from a single configuration file.
c. Filtering and Running Specific Projects via CLI
When managing multiple projects in a monorepo, running every test suite during quick local iterations is unnecessary. Vitest provides the --project CLI flag to target specific project names defined in your configuration.
Bash
# Run exclusively the client-dom project suite
npx vitest --project client-dom
# Run exclusively the server-api project suite in run mode
npx vitest run --project server-api
Developers can also pass multiple --project flags or glob patterns (e.g., --project "client-*" ) to execute subsets of related projects simultaneously during targeted debugging sessions.
Complete Example Session
TypeScript
// ============================================
// PART 1: UNIFIED ROOT CONFIGURATION SETUP
// ============================================
import { defineConfig } from 'vitest/config';
TypeScript
// ============================================
// PART 2: DEFINING GLOBAL DEFAULTS
// ============================================
export const baseConfig = defineConfig({
test: {
globals: true,
exclude: ['**/node_modules/**', '**/dist/**'],
},
});
TypeScript
// ============================================
// PART 3: CLIENT DOM PROJECT DEFINITION
// ============================================
export const clientProject = {
name: 'client',
test: {
environment: 'jsdom',
include: ['src/client/**/*.test.ts'],
},
};
TypeScript
// ============================================
// PART 4: SERVER NODE PROJECT DEFINITION
// ============================================
export const serverProject = {
name: 'server',
test: {
environment: 'node',
include: ['src/server/**/*.test.ts'],
},
};
TypeScript
// ============================================
// PART 5: E2E INTEGRATION PROJECT DEFINITION
// ============================================
export const e2eProject = {
name: 'e2e',
test: {
environment: 'node',
include: ['e2e/**/*.spec.ts'],
testTimeout: 30000,
},
};
TypeScript
// ============================================
// PART 6: COMBINING PROJECTS INTO ROOT CONFIG
// ============================================
export default defineConfig({
...baseConfig,
projects: [clientProject, serverProject, e2eProject],
});
TypeScript
// ============================================
// PART 7: SAMPLE CLIENT TEST FILE (src/client/ui.test.ts)
// ============================================
import { describe, expect, it } from 'vitest';
describe('Client DOM Suite', () => {
it('runs in jsdom environment', () => {
const div = document.createElement('div');
expect(div).toBeDefined();
});
});
TypeScript
// ============================================
// PART 8: SAMPLE SERVER TEST FILE (src/server/api.test.ts)
// ============================================
import { describe, expect, it } from 'vitest';
describe('Server Node Suite', () => {
it('runs in node environment', () => {
expect(typeof process).toBe('object');
});
});
TypeScript
// ============================================
// PART 9: CLI COMMAND INTEGRATION
// ============================================
export const cliCommands = {
runAll: 'npx vitest',
runClientOnly: 'npx vitest --project client',
};
TypeScript
// ============================================
// PART 10: SESSION FINALIZATION
// ============================================
// Multi-project configuration and execution pipeline validated successfully
Quick Reference
Configuration Properties
| Property | Target Scope | Purpose |
projects | vitest.config.ts | Array defining child test projects (replaces workspace files) |
name | Project Object | Identifies the project for CLI filtering |
environment | Project Test Config | Specifies runtime environment ('node', 'jsdom', 'happy-dom') |
include | Project Test Config | Glob patterns targeting test files for that specific project |
CLI Filtering Flags
| Flag | Purpose | Example |
--project <name> | Runs only the specified project | vitest --project server |
--project <glob> | Runs projects matching pattern | vitest --project "*-dom" |
Best Practices
✅ Do This:
TypeScript
projects: [{ name: 'client', test: { environment: 'jsdom' } }] // ✅
❌ Don’t Do This:
TypeScript
// maintain legacy vitest.workspace.ts files in modern Vitest codebases // ❌
✅ Do This:
TypeScript
npx vitest --project client // ✅
❌ Don’t Do This:
TypeScript
// run entire multi-package test suites when debugging a single component // ❌
✅ Do This:
TypeScript
defineConfig({ test: { globals: true }, projects: [...] }) // ✅
❌ Don’t Do This:
TypeScript
// duplicate global test configurations across every individual project // ❌
Common Pitfalls
| Pitfall | Why It Happens | Fix |
| Vitest ignoring child project configurations | Continuing to use vitest.workspace.ts instead of migrating to projects | Move workspace definitions into the projects array inside vitest.config.ts |
Unrecognized project name error with --project | Passing a name that does not match the name property defined in config | Verify project names match strings declared in the projects array |
| DOM globals failing in Node project tests | Incorrect environment assignment (environment: 'node') for UI component tests | Set environment: 'jsdom' or 'happy-dom' on the relevant client project |
Real-World Examples
1. Consolidating Client and Server Projects in Vitest Config
TypeScript
export default defineConfig({
projects: [
{ name: 'frontend', test: { environment: 'jsdom', include: ['src/client/**'] } },
{ name: 'backend', test: { environment: 'node', include: ['src/server/**'] } },
],
});
2. Inheriting Root Coverage Settings Across Projects
TypeScript
export default defineConfig({
test: { coverage: { provider: 'v8', all: true } },
projects: [{ name: 'unit', test: { include: ['src/**/*.test.ts'] } }],
});
3. Targeting a Specific Project via CLI During Debugging
Bash
npx vitest --project frontend
4. Configuring Separate Setup Files per Project
TypeScript
projects: [
{ name: 'app', test: { setupFiles: ['./src/setup.ts'] } },
{ name: 'api', test: { setupFiles: ['./server/setup.ts'] } },
]
5. Running Multiple Project Glob Patterns via CLI
Bash
npx vitest --project "frontend-*"
6. Defining Custom Timeouts for E2E Projects
TypeScript
projects: [
{ name: 'e2e', test: { testTimeout: 60000, include: ['e2e/**/*.spec.ts'] } },
]
7. Excluding Experimental Packages from Root Projects Array
TypeScript
projects: [
{ name: 'stable-core', test: { include: ['packages/core/**/*.test.ts'] } },
// experimental package omitted from projects array
]
8. Overridding Globals per Child Project
TypeScript
projects: [
{ name: 'strict-mode', test: { globals: false } },
]
9. Setting Up Path Aliases Globally for All Projects
TypeScript
export default defineConfig({
resolve: { alias: { '@': resolve(__dirname, './src') } },
projects: [{ name: 'app', test: { include: ['src/**/*.test.ts'] } }],
});
10. Executing Multi-Project Workflows in CI Pipelines
YAML
- name: Run All Vitest Projects
run: npx vitest run --coverage
Visual
Deprecated Workspace File vs. Unified Projects Array
┌────────────────────────────────────────────────────────┐
│ DEPRECATED: vitest.workspace.ts (Separate File) │
├────────────────────────────────────────────────────────┤
│ MODERN: vitest.config.ts (Unified projects Array) │
└────────────────────────────────────────────────────────┘
Multi-Project Execution Architecture
┌────────────────────────────────────────────────────────┐
│ Root vitest.config.ts │
└───────────────────────────┬────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Client DOM │ │ Server Node │ │ E2E Suite │
│ (jsdom env) │ │ (node env) │ │ (timeout 30s)│
└──────────────┘ └──────────────┘ └──────────────┘
CLI Project Filtering Workflow
┌────────────────────────────────────────────────────────┐
│ Developer Executes `npx vitest --project frontend` │
└───────────────────────────┬────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ Vitest Filters Execution Exclusively to 'frontend' │
└────────────────────────────────────────────────────────┘
Summary
| Item | Value |
| Concept | Multi-Project Configuration in Vitest |
| Deprecated Feature | vitest.workspace.ts / vitest.workspace.js |
| Replacement Property | projects array property in vitest.config.ts |
| Primary Benefit | Centralizes multi-environment test orchestration |
| Inheritance Model | Child projects inherit root test and resolve settings |
| CLI Filtering Flag | --project <name> or --project <glob> |
| Environment Control | Tailor environments (jsdom, node, happy-dom) per project |
| Setup Flexibility | Assign unique setupFiles and timeouts to individual projects |
| Monorepo Support | Manages client, server, and e2e suites under one runner |
| Architectural Alignment | Aligns with standard Vite multi-config patterns |
Key takeaways:
- Migrate away from workspace files. Replace deprecated
vitest.workspace.tsfiles with the unifiedprojectsarray property insidevitest.config.ts. - Centralize global defaults. Define shared settings like coverage providers, resolve aliases, and global flags at the root config level.
- Isolate environment runtimes. Assign appropriate environments (
jsdom,happy-dom, ornode) to each child project based on target execution requirements. - Target suites via CLI. Use the
--projectCLI flag to run specific project suites and accelerate local debugging loops. - Override project specifics. Customize setup files, include globs, and timeouts for individual projects without breaking root inheritance.
- Streamline monorepo architecture. Manage client apps, server APIs, and integration tests from a single, unified configuration file.
Remember: Vitest’s projects configuration eliminates the need for fragmented workspace files, bringing multi-environment test orchestration directly into vitest.config.ts. By centralizing global defaults while isolating client and server runtimes, engineering teams can manage complex monorepos with maximum clarity and zero configuration drift.
Stop using slow, ad-bloated tool sites! 🤮
🔎 Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)
⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free
🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!