Overview of the Nx Jest Plugin

Jest is a JavaScript testing framework.

The @nx/jest plugin adds inferred Jest targets, a Jest configuration generator, and CI-ready test splitting.

You can use Jest 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

Make sure to install the @nx/jest version that matches the version of nx in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can fix Nx version mismatches with this recipe. Using nx add helps ensure the correct version is installed and configured.

nx add @nx/jest

Verify the inferred test target in the project details view:

nx show project my-app

Add Jest to a project

Generate Jest configuration for an existing project:

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

Replace my-app with your project name.

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

React

nx g @nx/jest:configuration --project=my-react-lib --supportTsx

Enables the JSX/TSX transform so Jest can process React components.

Angular

nx g @nx/jest:configuration --project=my-angular-lib --setupFile=angular

Configures jest-preset-angular and keeps Angular snapshot serializers enabled.

Node / TypeScript

nx g @nx/jest: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 Jest as the test runner and Nx passes the correct options automatically:

nx g @nx/react:lib libs/my-react-lib --unitTestRunner=jest
nx g @nx/node:app apps/my-api --unitTestRunner=jest

Local Development

Run tests:

nx test my-app

Watch for changes:

nx test my-app --watch

Run a specific file (positional argument or --testFile):

nx test my-app ./path/to/spec/file/user-profile.spec.ts
nx test my-app --testFile user-profile.spec.ts

Collect coverage:

nx test my-app --coverage

Snapshot example:

describe('userProfile', () => {
  it('matches the saved snapshot', () => {
    expect(renderUserProfile()).toMatchSnapshot();
  });
});

Update snapshots with -u/--updateSnapshot and check snapshot files into source control.

Configuration

Task inference

The @nx/jest plugin infers tasks for any project with a Jest configuration file:

• jest.config.js
• jest.config.ts
• jest.config.mjs
• jest.config.mts
• jest.config.cjs
• jest.config.cts

Plugin options

Configure the plugin in nx.json:

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "options": {
        "targetName": "test"
      }
    }
  ]
}

Option	Type	Default	Description
targetName	string	test	Name of the inferred Jest target.
ciTargetName	string	none	Creates a CI-only target for atomized test tasks.
ciGroupName	string	none	Custom group name for atomized tasks in Nx Cloud/UI.
disableJestRuntime	boolean	true	When true, Nx skips creating the Jest runtime and computes inputs/outputs itself. Set to false to enable the Jest runtime.

disableJestRuntime defaults to true because the plugin treats it as enabled only when options.disableJestRuntime !== false. This reduces computation time for inferred tasks; set it to false if you need Jest runtime inference.

Unit and e2e configurations

Use two plugin entries to separate unit and E2E Jest tasks, and enable CI splitting for E2E:

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "exclude": ["e2e/**/*"],
      "options": {
        "targetName": "test"
      }
    },
    {
      "plugin": "@nx/jest/plugin",
      "include": ["e2e/**/*"],
      "options": {
        "targetName": "e2e",
        "ciTargetName": "e2e-ci"
      }
    }
  ]
}

ciTargetName enables split E2E tasks so each test file runs as its own CI task with better caching and retries. Use ciGroupName if you want a custom group label.

View inferred tasks

Open the project details view in Nx Console or run:

nx show project my-app

CI Considerations

See Set Up CI for a complete CI configuration guide.

Build and Test Only What Changed

nx affected -t build test typecheck lint

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 build and typecheck 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.

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.

Performance with Parallelization

Typically, in CI it's recommended to use nx affected -t test --parallel=[# CPUs] --runInBand for the best performance.

This is because each jest process creates workers based on system resources, running multiple projects via Nx and using jest workers will create too many processes overall causing the system to run slower than desired. Using the --runInBand flag tells jest to run in a single process. You can then leverage Nx parallelism to run multiple jest projects at once.

Batch Mode

For large monorepos with many Jest projects, Batch mode can improve performance by batching compilation across projects into a single process.

NX_BATCH_MODE=true nx run-many -t test

What's Next

Jest Configuration Explore all Jest configuration options.

Snapshot Testing Learn how Jest snapshot testing works and when to use it.

Split E2E Tasks Distribute E2E tests across CI for better caching and retries.

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

Jest Generators Reference Full API reference for @nx/jest generators.

Jest Executors Reference Full API reference for @nx/jest executors.