What is the Nx Atomizer and how does it work?
The Atomizer is a feature of Nx's inferred-task plugins for Jest and Vitest. When you enable it, the plugin reads your test configuration, finds the spec files in each project, and creates one test target per spec file. It also creates a parent CI target, conventionally named something like test-ci, that does no work itself and only depends on all of those per-file targets. Your normal test target stays as it is for local use.
How the task graph changes
Without the Atomizer, a project with 40 spec files contributes one node to the task graph: test. Nx can only schedule, cache, or retry that node as a whole. The task runs on one machine, and its duration is the sum of every file in the project, minus whatever parallelism the test runner manages inside that single process.
With the Atomizer, the same project contributes 40 leaf tasks plus the parent. Three things follow from that:
- Caching is per file. A change that invalidates one spec's inputs reruns only that spec. The other 39 can be restored from cache, assuming their inputs didn't change.
- Distribution is per file. A distributed executor can spread the 40 tasks across several agents. Your slowest project no longer sets the lower bound on CI time. The slowest individual file does.
- Failures and retries are scoped. A flaky spec fails its own task. You rerun that task, not the whole suite.
In practice, you run the parent target in CI and keep the monolithic target for development.
WITHOUT ATOMIZER WITH ATOMIZER
project: api (40 spec files) project: api (40 spec files)
+---------------------------+ +------------------------------+
| test | | test-ci (parent, no work) |
| 1 task, 1 cache entry | +------------------------------+
| runs spec-1 ... spec-40 | | | | |
+---------------------------+ v v v v
| +------+ +------+ +-----+ +-------+
v |spec-1| |spec-2| | ... | |spec-40|
+---------------------------+ +------+ +------+ +-----+ +-------+
| 1 agent | | | |
| time = sum of all files | v v v
+---------------------------+ +---------+ +---------+ +---------+
| agent A | | agent B | | agent C |
1 spec changes -> rerun all 40 +---------+ +---------+ +---------+
1 flaky spec -> retry all 40 1 spec changes -> rerun 1, rest cached
1 flaky spec -> retry 1 task
CI time >= slowest single file
Local dev keeps the monolithic `test` target; CI runs `test-ci`.
Without the Atomizer a project is a single test task that runs and caches as one unit on one agent; with it, a no-op test-ci parent depends on one task per spec file, so Nx can cache, distribute, and retry each file on its own.
Who should use the Nx Atomizer, and when does it pay off?
The Atomizer is worth enabling when one test target dominates your CI critical path and you can run tasks on more than one machine. A typical case is a monorepo where most projects test in under a minute but a single service or shared library takes fifteen. Every pull request that touches that project waits for that one long task, however fast everything else is.
Why a single machine gains little
On one agent, splitting per file changes little. Jest already spreads test files across worker processes, and Vitest already runs files in parallel threads or forks. Both use the CPU cores you have. Atomizing the target turns that internal parallelism into Nx tasks competing for the same cores, and each task pays its own startup cost: loading config, initializing transforms, building the module graph. The suite can end up slightly slower.
Where it pays off
The gains come from two places:
- Distribution. With several agents, per-file tasks can be scheduled across machines. The longest path through CI shrinks toward the duration of your slowest spec file rather than the whole suite.
- Fine-grained caching. Each file's result is cached on its own. A change that affects a few specs reruns only those, and the rest are restored from cache.
For engineers, this shows up as shorter feedback loops. A developer pushing a fix to one module waits for that module's tests, not for the whole suite to rerun. That matters most on teams where pull requests queue behind CI dozens of times a day.
What do you need before enabling the Atomizer?
The Atomizer works only on targets that Nx infers. The Jest and Vitest plugins registered under plugins in nx.json read each project's config file and create the test targets from it. The per-file split happens at that inference step. The plugin finds the spec files and generates one CI target per file. A target defined by hand in project.json with an executor field never goes through inference, so it cannot be split. Nx runs it as a single task.
Check what Nx actually built before you change anything. Run nx show project <name> (add --web for a browsable view). For each target, the output shows whether a plugin inferred it or project.json defined it, and which config file it came from. If your test target lists an executor and no plugin source, that project needs to be migrated first.
Workspaces with custom test executors or heavily customized test targets need some migration work:
- Move options into the tool's config file. Coverage thresholds, setup files, environment settings and module mappings belong in
jest.configor the Vitest config, where the plugin can read them. Any executor option that has no equivalent in the config file must be replaced or dropped. - Remove the explicit target from
project.json. If you leave it, it shadows or merges with the inferred one, and the split targets may not show up. - Use the conversion generators where they fit. Nx provides
convert-to-inferredgenerators for its plugins. Review their diff carefully, especially in projects with wrapper scripts around the test runner. - Check
targetDefaults. Inputs, outputs anddependsOnset there apply by target name, so make sure they still match the names of the inferred targets.
# 1. Inspect what Nx built for the project before changing anything.
# Hand-written targets show an executor from project.json.
# Inferred targets show the plugin and config file they came from.
npx nx show project my-app
npx nx show project my-app --web # browsable view of the same data
# 2. Convert hand-written Jest targets to inferred ones.
# Review the diff before committing, especially where wrapper
# scripts or custom executor options were involved.
npx nx g @nx/jest:convert-to-inferred --project=my-app
git diff -- apps/my-app/project.json apps/my-app/jest.config.ts nx.json
# 3. Confirm the split happened. With the Jest plugin registered in
# nx.json and a ciTargetName (e.g. "test-ci") set in its options,
# you should see one test-ci--<spec file> target per spec file
# alongside the aggregate test-ci target.
npx nx show project my-app --json | jq -r '.targets | keys[]' | grep '^test-ci'
Inspecting a project's targets with nx show project, converting a hand-written Jest target to an inferred one, and checking that per-file CI targets now exist.
How do you configure the Atomizer for Jest and Vitest in nx.json?
Atomization is enabled per plugin entry in the plugins array of nx.json. For Jest, that entry is @nx/jest/plugin. For Vitest, it is the Vite or Vitest plugin your workspace uses to infer test targets. Alongside the existing targetName option, add a CI target name option, commonly ciTargetName, with a value such as test-ci. The plugin then infers two kinds of target. The original test target still runs the whole suite in one process, so local workflows, watch mode and editor integrations behave as before. The new CI target is a parent task whose dependencies are one task per spec file. Option names and defaults have changed between plugin releases, so check them against the documentation for the version in your lockfile.
In CI, replace the existing test step with nx affected -t test-ci. Nx expands the parent into its per-file tasks, schedules them across available agents or processes, and caches each one independently.
Before relying on it, run nx graph or nx show project <name> --web and open the project's targets. Confirm that the CI target exists, that it has one child per spec file, and that your expected spec files all appear in that list. A missing file usually means the plugin's test-file glob doesn't match your naming convention.
Then check the inputs for those tasks. Each per-file task hashes its own spec file plus whatever inputs the plugin and your namedInputs assign. Make sure that hash also covers these files:
- Setup files
- Global mocks
- Custom environments
- The runner config
- Shared test utilities
If one of them is missing, editing it won't invalidate the cache. Nx will replay old passing results, and a real regression reaches main unnoticed.
{
// nx.json (Nx parses this file as JSON with comments)
"namedInputs": {
// Files that affect every test task. Editing any of these must bust the cache.
"sharedGlobals": [
"{workspaceRoot}/jest.preset.js",
"{workspaceRoot}/tools/test-setup/**/*",
"{workspaceRoot}/tools/test-utils/**/*"
],
// Per-project files: source, setup files, mocks and the runner config.
"default": ["{projectRoot}/**/*", "sharedGlobals"],
// Exclude tests from what dependent projects hash.
"production": [
"default",
"!{projectRoot}/**/*.spec.ts",
"!{projectRoot}/jest.config.ts",
"!{projectRoot}/vite.config.ts",
"!{projectRoot}/src/test-setup.ts"
]
},
"plugins": [
{
"plugin": "@nx/jest/plugin",
"options": {
// Local target: unchanged, runs the whole suite in one process.
"targetName": "test",
// CI target: parent task with one child task per spec file.
"ciTargetName": "test-ci"
}
},
{
"plugin": "@nx/vite/plugin",
"options": {
// Option names differ between releases. Check the docs for your installed version.
"testTargetName": "test",
"ciTargetName": "test-ci"
}
}
]
}
An nx.json that adds a separate per-file CI test target for Jest and Vitest and puts shared setup files and runner config into namedInputs, so editing them invalidates the cache.
When should you avoid splitting tests per file?
Each atomized task is a separate runner invocation, so it pays the full startup cost: process spin-up, transformer warm-up, TypeScript compilation of shared imports, and test environment creation. When a file's tests run in milliseconds, that overhead dominates. A project whose whole suite already finishes in seconds will usually get slower in aggregate once you split it.
| Cost | Why it happens | Mitigation |
|---|---|---|
| Repeated startup | Every file boots its own runner and environment | Atomize only projects whose suites are actually slow |
| Expensive global setup | Global setup runs once per task, not once per suite | Provision containers or seed data in a CI step before tests run |
| Hidden coupling | Files that shared one process now run concurrently in separate processes | Isolate ports, databases, and filesystem paths per task |
| Noisy task graph and logs | One task per file instead of one per project | Read results through the aggregate parent target |
| Fragmented coverage | Each task writes its own report | Merge reports before enforcing global thresholds |
Hidden coupling deserves the most attention. Tests that passed by accident, such as a module-level singleton populated by an earlier file, a server hardcoded to one port, or a fixture that assumes a prior test inserted rows, fail once files run independently. Fix them at the source. Bind servers to port 0 and read back the port the OS assigned. Create a uniquely named database or schema per task, then drop it on teardown. Move shared global setup out of the runner, or make it idempotent and keyed per task. Each file must also reset any state it depends on, so it passes when run alone.
How does the Atomizer affect CI time and cost? An illustrative estimate
Illustrative estimate (assumed numbers, not a benchmark). Assume one test target with N = 120 spec files. Each file takes t = 15 s of actual test work. Every task pays o = 8 s of startup (runner boot, config load, transform cache warm-up), and each CI agent pays A = 60 s to check out the repo and install dependencies. Treat the unsplit run as serial for simplicity. Jest and Vitest workers do parallelise inside one process, which shrinks the unsplit baseline, so plug in your own measured time for that baseline.
With k agents:
- Unsplit: wall clock ≈ A + o + N·t
- Split per file: wall clock ≈ A + N·(o + t) / k
- Split compute ≈ k·A + N·(o + t)
| Scenario | Wall clock | Compute |
|---|---|---|
| 120 files, unsplit, 1 agent | ~31 min | ~31 min |
| 120 files, split, 10 agents | ~5.6 min | ~56 min |
| 10 files (t = 3 s), unsplit, 1 agent | ~98 s | ~98 s |
| 10 files (t = 3 s), split, 1 agent | ~170 s | ~170 s |
Distribution cuts wall-clock time because the files run concurrently. Total compute rises because the 8 s startup is paid 120 times instead of once, and the 60 s agent setup is paid ten times. For the small suite on one agent there is nothing to parallelise across, so splitting only adds repeated overhead and makes the run slower.
Per-file caching can win some compute back: if only a few files are affected by a change, only those tasks rerun. Still, o and A dominate this calculation, and they vary widely between repositories. Measure both in your own pipeline before you decide how far to split.
What are the alternatives to the Nx Atomizer?
These options are not mutually exclusive with the Atomizer or with each other, but they make different trade-offs.
| Option | Setup effort | Cache granularity | Distribution support | Overhead |
|---|---|---|---|---|
| Runner parallelism (Jest workers, Vitest threads or forks) | Low | Whole project | None; limited to one machine | Worker startup and memory per worker |
Runner sharding (--shard across CI jobs) |
Medium; requires a CI matrix | Whole project per shard, unless you wire up caching yourself | Fixed number of jobs | Each job repeats checkout, install and bootstrap |
| Splitting into smaller Nx projects | High; requires refactoring boundaries | Per project | Full Nx task distribution | More project configuration to maintain |
| Nx affected with project-level caching | Low if you already use Nx | Per project | Project-level only | One slow project is still one task |
Runner parallelism is the first thing to tune because it costs almost nothing. It stops helping once a single machine runs out of cores or memory.
Sharding spreads the work further. However, shards are assigned by file rather than by measured duration, so one shard can end up much slower than the others. A cache hit also requires the whole shard's inputs to be unchanged.
Splitting the project gives you the most durable result. Smaller projects improve caching and dependency boundaries for every target, not only tests. The cost is real refactoring work.
Affected runs with project-level caching are the baseline the Atomizer builds on. They skip untouched projects, but a change to any file in a large project reruns that project's entire suite.
How to roll out the Atomizer incrementally
Start small so that any regression has an obvious cause and you can revert it in one commit.
1. Pick one project and record a baseline
Choose the project whose test target takes the longest wall-clock time in CI. Record its duration and total compute usage (agent or runner minutes summed across machines) over several runs. A single run is noisy. Compute is the number that tends to rise after atomizing, so you need it from the start.
2. Scope the plugin to that project
Add a second entry for the Jest or Vitest plugin in nx.json that sets the CI target name option. Use the entry's include glob so it matches only that project's directory. Add the same path to exclude on your existing plugin entry so the project is not configured twice. Every other project keeps its current single test target, and you can revert by deleting one entry.
3. Fix isolation failures
Run the per-file targets in your pipeline. Failures here usually point to tests that depended on execution order, shared module state, or a fixture created by another file. Fix the test rather than grouping files back together, because hidden coupling between files will cause problems again later.
4. Compare before and after
Measure wall-clock time and compute in your own pipeline using the same number of runs you used for the baseline.
5. Check cache behavior
Change a file that many tests import, then count how many per-file tasks rerun. If nearly all of them rerun, the gain on that kind of change is small.
6. Expand or revert
Expand to the next slowest project if the trade-off holds. If it doesn't, remove the entry.
{
"plugins": [
{
"plugin": "@nx/jest/plugin",
"exclude": ["libs/billing/**/*"],
"options": {
"targetName": "test"
}
},
{
"plugin": "@nx/jest/plugin",
"include": ["libs/billing/**/*"],
"options": {
"targetName": "test",
"ciTargetName": "test-ci"
}
}
]
}
An nx.json fragment that turns on the Jest plugin's per-file CI target (test-ci) for libs/billing only. The original plugin entry excludes that path so the project is not configured twice, and deleting the second entry reverts the change.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to nx atomizer, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.