| | |

Vitest 24 🧪 Projects Configuration — Replacing deprecated workspace with projects

⏱️ Estimated read: 8 min | |

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

PropertyTarget ScopePurpose
projectsvitest.config.tsArray defining child test projects (replaces workspace files)
nameProject ObjectIdentifies the project for CLI filtering
environmentProject Test ConfigSpecifies runtime environment ('node', 'jsdom', 'happy-dom')
includeProject Test ConfigGlob patterns targeting test files for that specific project

CLI Filtering Flags

FlagPurposeExample
--project <name>Runs only the specified projectvitest --project server
--project <glob>Runs projects matching patternvitest --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

PitfallWhy It HappensFix
Vitest ignoring child project configurationsContinuing to use vitest.workspace.ts instead of migrating to projectsMove workspace definitions into the projects array inside vitest.config.ts
Unrecognized project name error with --projectPassing a name that does not match the name property defined in configVerify project names match strings declared in the projects array
DOM globals failing in Node project testsIncorrect environment assignment (environment: 'node') for UI component testsSet 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

ItemValue
ConceptMulti-Project Configuration in Vitest
Deprecated Featurevitest.workspace.ts / vitest.workspace.js
Replacement Propertyprojects array property in vitest.config.ts
Primary BenefitCentralizes multi-environment test orchestration
Inheritance ModelChild projects inherit root test and resolve settings
CLI Filtering Flag--project <name> or --project <glob>
Environment ControlTailor environments (jsdom, node, happy-dom) per project
Setup FlexibilityAssign unique setupFiles and timeouts to individual projects
Monorepo SupportManages client, server, and e2e suites under one runner
Architectural AlignmentAligns with standard Vite multi-config patterns

Key takeaways:

  • Migrate away from workspace files. Replace deprecated vitest.workspace.ts files with the unified projects array property inside vitest.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, or node) to each child project based on target execution requirements.
  • Target suites via CLI. Use the --project CLI 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.

Was this helpful?


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!