Overview of the Nx Vitest Plugin

Vitest is a fast test runner built on Vite.

The @nx/vitest plugin adds inferred Vitest targets, a project configuration generator, and CI-friendly test splitting.

You can use Vitest with Nx without the plugin and still get task caching, task orchestration, and the project graph.

Setup

Add to an existing workspace

Keep Nx Package Versions In Sync

Install the @nx/vitest version that matches the version of nx in your workspace. If the version numbers get out of sync, you can encounter difficult to debug errors. Use the version sync recipe to fix mismatches. Using nx add helps ensure the correct version is installed and configured.

nx add @nx/vitest

Verify inferred tasks

Nx infers Vitest tasks from your Vitest or Vite config files. To confirm which targets were created, open the project details view in Nx Console or run:

nx show project my-app

Add Vitest to a project

Use the configuration generator to set up a project with Vitest:

nx g @nx/vitest:configuration --project=my-app

The generator accepts framework-specific options. Pass the right flags for your project type:

React

nx g @nx/vitest:configuration --project=my-react-lib --uiFramework=react

Sets up Vitest with React JSX support and jsdom test environment.

Vue

nx g @nx/vitest:configuration --project=my-vue-lib --uiFramework=vue

Sets up Vitest with Vue SFC support and jsdom test environment.

Angular

nx g @nx/vitest:configuration --project=my-angular-lib --uiFramework=angular

Configures Vitest for Angular with the appropriate test setup.

Node / TypeScript

nx g @nx/vitest:configuration --project=my-node-lib --testEnvironment=node

Uses the node test environment instead of the default jsdom.

See the full configuration generator reference for all options.

Framework generators handle this automatically

When generating a new project with a framework generator, you can specify Vitest as the test runner and Nx passes the correct options automatically:

nx g @nx/react:lib libs/my-react-lib --unitTestRunner=vitest
nx g @nx/vue:lib libs/my-vue-lib --unitTestRunner=vitest

Local Development

Run Vitest through Nx so caching and the project graph work together.

nx test my-app

nx test my-app --watch

nx test my-app -- MyComponent.spec.ts

nx test my-app --ui

nx test my-app --coverage

Replace the project name

Replace my-app with the name of your project and the test file pattern with the file you want to run.

Configuration

How tasks are inferred

The @nx/vitest plugin creates a target for any project that has a Vitest or Vite config file with test settings. The plugin looks for:

• vitest.config.js
• vitest.config.ts
• vitest.config.mjs
• vitest.config.mts
• vitest.config.cjs
• vitest.config.cts
• vite.config.js (with test configuration)
• vite.config.ts (with test configuration)
• vite.config.mjs (with test configuration)
• vite.config.mts (with test configuration)
• vite.config.cjs (with test configuration)
• vite.config.cts (with test configuration)

To view inferred tasks, open the project details view in Nx Console or run nx show project my-app.

Plugin options

Configure the plugin in nx.json:

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/vitest",
      "options": {
        "testTargetName": "test",
        "ciTargetName": "test-ci",
        "ciGroupName": "Unit Tests (CI)",
        "testMode": "watch"
      }
    }
  ]
}

Option	Type	Default	Description
testTargetName	string	test	Name of the inferred local target.
ciTargetName	string	none	Creates a CI-only target used for atomized runs.
ciGroupName	string	derived from ciTargetName	Display name for the atomized CI group.
testMode	watch or run	watch	Determines whether Nx runs vitest (watch) or vitest run (single run).

There is no single "disable" flag for inference. Use include and exclude to scope which projects each plugin instance applies to.

Configure unit and e2e separately

If you use Vitest for unit and e2e tests, configure the plugin twice with different include and exclude patterns.

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/vitest",
      "exclude": ["e2e/**/*"],
      "options": {
        "testTargetName": "test",
        "testMode": "watch"
      }
    },
    {
      "plugin": "@nx/vitest",
      "include": ["e2e/**/*"],
      "options": {
        "testTargetName": "e2e",
        "ciTargetName": "e2e-ci",
        "ciGroupName": "E2E Tests (CI)",
        "testMode": "run"
      }
    }
  ]
}

CI Considerations

See Set Up CI for a complete CI configuration guide.

Build and Test Only What Changed

nx affected -t test

This uses the project graph to determine which projects are affected by your changes and only runs tasks for those. Read more about the benefits of nx affected.

Remote Caching

Share test and e2e cache results across your team and CI with remote caching:

nx connect

Task Splitting for Slow Tests

For slow test suites (e.g. E2E or integration tests), set ciTargetName to split tests by file for distributed CI runs. Each test file becomes its own cacheable CI task with better caching and retries. See split e2e tasks for details.

If you use testMode: "watch" locally, use testMode: "run" for CI to keep runs deterministic.

Feature-Based Testing

Organize tests by feature to get better cache hits and more targeted CI runs. See the feature-based testing guide for strategies on structuring tests in a monorepo.

What's Next

Vitest Config Reference Learn about Vitest configuration options and defaults.

Migrate from @nx/vite Move Vitest tasks from the Vite plugin to @nx/vitest.

Split E2E Tasks Distribute E2E tests by file with atomized tasks.

Feature-Based Testing Organize tests by feature for better caching and targeted CI.

Vitest Generators Reference Reference for @nx/vitest generators.

Vitest Executors Reference Reference for @nx/vitest executors.