Nx with Vitest

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.

The @nx/vitest plugin supports the following package versions.

Nx generators install the latest supported versions automatically when scaffolding new projects.

nx add @nx/vitest

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

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:

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

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

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

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

See the full configuration generator reference for all options.

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

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)

The configuration directory must also contain a package.json or project.json. A root Vitest workspace configuration that only orchestrates child projects is not registered as its own project.

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

Configure the plugin in nx.json:

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

When discoverTestFiles is glob, configs that a glob cannot reproduce faithfully still boot Vitest automatically: test.projects or test.workspace (inline or an auto-loaded vitest.workspace.* or vitest.projects.* file), plugins with a configureVitest hook, test.changed or test.related, and enabled browser instances that set their own include, exclude, includeSource, or dir. Patterns the glob reads differently than Vitest trigger the same fallback: an absolute path, a trailing /, or an !(...) extglob, each optionally negated, in include, exclude, includeSource, or typecheck's include or exclude.

The glob path reads the Nx workspace file index, so it never enumerates specs ignored by .gitignore or .nxignore, even ones Vitest itself would run. Set discoverTestFiles to vitest if you need those specs atomized.

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

The test task is cached, with outputs based on your Vitest coverage configuration. Custom reporter output files are not inferred. Set ciTargetName to enable the Atomizer.

A target defaults plugin filter for these tasks must use the exact identifier @nx/vitest.

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

{
  "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"
      }
    }
  ]
}

In CI, Nx runs nx affected to rebuild and retest only the projects a change touches, and caches results to skip repeated work.

For a complete pipeline, see Set up CI.