What are Nx inferred tasks and what was Project Crystal?

Inferred tasks are targets that Nx creates for you instead of reading them from a project.json file. You register plugins in the plugins array of nx.json. Each plugin scans the workspace for the config files of the tool it understands, such as vite.config.ts for Vite or jest.config.ts for Jest. For every match, the plugin synthesizes a target: the command to run, the inputs that affect its result, the outputs it produces, and whether it can be cached. A project with a vite.config.ts gets build, serve and test targets even though no file in that project declares them.

Project Crystal was the name Nx used for the effort to make inference the default way of defining tasks. Before it, every project carried explicit target definitions that pointed at executors and repeated paths the tool config already held.

The main benefit is removing duplicated configuration. In an explicit setup, the output directory lives in vite.config.ts and again in the outputs of the build target. When someone changes one and forgets the other, caching breaks without any error. Nx restores a stale or incomplete artifact, or it skips caching files that should have been cached. When the plugin reads the tool config directly, the tool config is the only place that path is defined.

The benefit grows with the number of projects. Consider a platform team running dozens of backend services or libraries that use the same test runner and build tool. Without inference, each one needs a near-identical project.json that someone has to keep in sync. With inference, adding a project takes only a tool config file, and a change to how a whole category of projects is built happens once, in the plugin options.

cat > nx.json <<'EOF'
{
  "plugins": [
    {
      "plugin": "@nx/vite/plugin",
      "options": {
        "buildTargetName": "build",
        "serveTargetName": "serve",
        "testTargetName": "test"
      }
    },
    {
      "plugin": "@nx/jest/plugin",
      "options": {
        "targetName": "test"
      }
    }
  ]
}
EOF

npx nx show project orders-api --json

npx nx build orders-api

An nx.json that registers the Vite and Jest inference plugins, then uses nx show project to inspect the targets Nx synthesized for a project that has no target definitions of its own.

Who should use inferred tasks?

Inferred tasks fit best in these situations:

  • Workspaces with many projects built by the same tools. If most projects use the same build tool and test runner, a plugin replaces many near-identical target definitions with one registration in nx.json.
  • Teams that already keep tool config files as the source of truth. If each project already has a vite.config.ts, jest.config.ts or similar, the plugin can read paths and settings from it instead of you repeating them.
  • Platform or tooling teams responsible for how a whole category of projects builds. They can change behavior in one plugin option or one custom plugin instead of editing every project.
  • Teams adopting Nx on an existing repository. Projects can start getting cached, graph-aware targets from their existing tool configs without anyone writing per-project Nx configuration.

Inference is a weaker fit for small workspaces with a few one-off projects, for tools that have no maintained plugin, and for teams that need every task definition visible in a file next to the project. The last section covers these cases in more detail.

How does it work?

At a high level, inference has three steps:

  1. Discovery. Each plugin registered in nx.json declares a file pattern. When Nx computes the project graph, it finds every file in the workspace that matches.
  2. Inference. The plugin reads each matched config file and returns partial project configuration: target names, commands, inputs, outputs and cache settings.
  3. Merging. Nx combines what all plugins returned, applies targetDefaults from nx.json, then applies any explicit settings in project.json or package.json. The result is the project graph that nx run, nx affected and the cache use.

From the point of view of someone running tasks, nothing changes: nx build web runs an inferred target the same way it runs an explicit one. The next two sections cover the inference hook (createNodes) and the merge rules in detail.

How does createNodes build targets from your config files?

A plugin is registered in the plugins array of nx.json. Its inference hook pairs two things: a glob pattern, such as one matching every Jest or Vite config file in the workspace, and a function. When Nx builds the project graph, it matches the glob against workspace files and passes the matches to that function. It also passes the plugin's options from nx.json and a context object that includes the workspace root and the nx.json configuration. The function returns fragments keyed by project root. A fragment is partial project configuration: targets with their commands, inputs, outputs, and sometimes metadata like a project name or tags.

This design has three consequences. First, the config file itself marks a project, so a directory with a vitest.config.ts can become a project without any Nx-specific file. Second, the plugin can read that config to infer details. For example, it can find where the tool writes output so caching captures the right paths. Third, current Nx versions hand all matching files to the function in one call, so a plugin can batch expensive work like loading a tool's config resolver once.

Fragments from all plugins are then combined, in the order plugins are listed. Section 3 covers the precedence rules.

Config files (matched by each plugin's glob) → Plugin inference functions (return project and target fragments) → Merged with targetDefaults → Overridden by project.json / package.json → Final project graph

Nx caches the resulting graph and reruns inference when the relevant files change.

 Workspace files (matched by each plugin's glob in nx.json)
 +------------------+  +------------------+  +------------------+
 | apps/web/        |  | libs/ui/         |  | libs/api/        |
 |  vite.config.ts  |  |  jest.config.ts  |  |  jest.config.ts  |
 +--------+---------+  +--------+---------+  +--------+---------+
          |                     |                     |
          v                     +----------+----------+
 +------------------+                      v
 | Vite plugin      |           +----------------------+
 | glob + function  |           | Jest plugin          |
 | (files, options, |           | glob + function      |
 |  context)        |           | (all matches at once)|
 +--------+---------+           +----------+-----------+
          |   fragments by project root    |
          +---------------+----------------+
                          v
           +----------------------------+
           | Combine fragments          |
           | (in nx.json plugin order)  |
           +--------------+-------------+
                          v
           +----------------------------+
           | Merge with targetDefaults  |
           +--------------+-------------+
                          v
           +----------------------------+
           | Apply explicit overrides   |<-- project.json / package.json
           +--------------+-------------+
                          v
          [ Final project graph (cached) ]

Each plugin matches config files by glob, its inference function returns fragments keyed by project root, and Nx combines them, applies targetDefaults, then project.json or package.json overrides to build the cached project graph.

How do inferred targets merge with targetDefaults and project.json?

Precedence follows that pipeline order: each stage refines what the previous one produced, so the most specific source wins. Explicit configuration in project.json, or in the nx field of package.json, sits closest to the project and therefore overrides both plugin output and targetDefaults. When two plugins infer a target with the same name, the plugin listed later in the plugins array of nx.json takes precedence.

Source Scope Role in the merge
Plugin inference (createNodes) Every project matching the plugin's file pattern Supplies the baseline target: command, options, inputs, outputs
targetDefaults in nx.json Workspace-wide, keyed by target name or executor Applies shared settings such as dependsOn or cache across projects
project.json / package.json A single project Final override for that project only

You don't have to redefine a whole target to change it. Declare the target name in project.json and set only the property you need, such as outputs. Nx merges that entry with the inferred target. Two details matter here. Objects like options are merged key by key. Arrays like inputs and outputs replace the inferred value instead of appending to it. To add one input, copy the inferred list and extend it, otherwise you drop the inputs the plugin derived.

Mixed workspaces have a quieter failure mode. A fully specified target left over from before migration still overrides inference. If the plugin later starts inferring better inputs or outputs, for example after it learns to read a new config file, that project never picks them up and nothing reports the conflict. During migration, remove old explicit targets unless they exist to override something on purpose.

// apps/web/project.json
// Inferred targets can be inspected with: nx show project web --web
{
  "name": "web",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "targets": {
    // Only the properties declared here change; command and other
    // inferred settings still come from the plugin.
    "build": {
      // Arrays REPLACE the inferred value. This list copies the
      // inferred inputs, then appends one extra file to hash.
      "inputs": [
        "production",
        "^production",
        { "externalDependencies": ["vite"] },
        "{projectRoot}/build-flags.json"
      ],
      // Replaces the inferred outputs with a different directory.
      "outputs": ["{workspaceRoot}/dist/apps/web-custom"],
      // Objects merge key by key: this adds one option and keeps
      // any options the plugin inferred.
      "options": {
        "mode": "staging"
      }
    }
    // Leftover pre-migration targets such as a full "test" entry
    // would shadow the inferred one. Remove them unless intentional.
  }
}

A project.json that overrides only inputs, outputs and one option of an inferred build target, copying the inferred inputs because arrays replace rather than append.

How do you see what Nx actually inferred?

Because targets are now computed rather than written down, the only reliable answer to "what will nx run api:build actually do?" comes from asking Nx. nx show project api prints the fully resolved configuration: every target after plugin inference, targetDefaults, and project.json overrides have been merged, including the final command or executor, inputs, outputs, dependsOn, and cache settings. Adding --web opens the same data in a browser view that also indicates which plugin or file contributed each target. nx graph shows how those targets connect across projects. During migration, treat this output as the source of truth. A project.json that looks correct tells you little if a plugin, or a broad targetDefaults entry, changes the result.

This is the main cost of inference. Targets no longer live in a file you can grep, and a code reviewer reading a diff to vite.config.ts may not realize it just changed a cached task's outputs. Newcomers and reviewers have to learn these commands, and answering "why does this target exist, and why does it look like this?" can mean reading the plugin's createNodes implementation and working through the merge order yourself.

Inference can also change without any edit to your repository. A plugin release may infer new targets, rename them, or adjust inputs. To catch that, capture nx show project <name> --json for your key projects before an Nx upgrade, regenerate it afterward, and diff the two. Keep plugin versions pinned and aligned with the nx version, so a change in inferred behavior only arrives through a deliberate upgrade.

#!/usr/bin/env bash
set -euo pipefail

PROJECTS=(api web shared-utils)   # key projects to track
mkdir -p .nx-snapshots/before .nx-snapshots/after

snapshot() {
  local dir=$1
  for p in "${PROJECTS[@]}"; do
    # Fully merged config: inferred targets + targetDefaults + project.json.
    # jq -S sorts keys so the diff only shows real changes.
    npx nx show project "$p" --json | jq -S . > ".nx-snapshots/$dir/$p.json"
  done
}

snapshot before

npx nx migrate latest
npm install
if [ -f migrations.json ]; then
  npx nx migrate --run-migrations
fi

npx nx reset
snapshot after

diff -ru .nx-snapshots/before .nx-snapshots/after || true

A script that captures nx show project --json output for key projects before and after an nx migrate upgrade and diffs them, so silent changes in plugin-inferred targets surface in review.

How do you migrate from project.json targets to inferred tasks incrementally?

Migrate one plugin at a time, starting with a tool whose config files are already consistent across the repo.

  1. Register the plugin in the plugins array of nx.json. Set the plugin's target-name options so inferred targets reuse the names your CI scripts and targetDefaults already reference. That keeps nx affected -t build working unchanged.
  2. Scope it. Use the plugin entry's include/exclude patterns so inference applies only to the projects you are converting. Confirm the exact option names in your installed plugin's documentation, because they differ between plugins and releases. Narrow scoping limits how many projects a misconfigured plugin can affect.
  3. Compare on a few projects. Pick two or three representative projects. Check the resolved command, inputs, outputs and dependsOn for each target with the inspection tools from the previous section.
  4. Delete redundant explicit targets from project.json once the inferred version matches. Keep explicit entries only for real overrides.
  5. Verify with real runs. Run affected builds and tests, then run them again. Cache hits on the second run and identical output directories are the signal that inputs and outputs were inferred correctly.

Nx ships migration generators for some official plugins that rewrite project.json for you. Check what your installed version provides instead of assuming a specific command exists.

The payoff is fewer copy-pasted targets. A change to how build runs becomes one plugin option instead of an edit to every project. The cost comes first: careful diffing of each project archetype and a few CI cycles of watching cache behavior. This work scales with the number of distinct project shapes in the repo, not with the number of projects.

How can inferred tasks save engineering time?

The time savings come from three places.

  • Fewer edits per change. Changing how a category of projects builds or tests becomes one change to plugin options or targetDefaults, reviewed once, instead of a change repeated across every project.json.
  • Less setup per new project. A new library or service needs its tool config file. It doesn't need a hand-written set of Nx targets copied from a neighboring project and adjusted.
  • Fewer cache bugs from drift. When output paths and inputs come from the tool config, they can't silently diverge from a second copy in project.json. That removes a class of stale-artifact and missing-output problems that are slow to diagnose because nothing reports an error.

An illustrative estimate, with assumed inputs: assume a workspace of 40 projects with explicit targets, and a change to a shared build flag that takes about 3 minutes per project.json to edit and check. That is roughly 2 hours of editing, plus review of a 40-file diff. With inference, the same change is one edit in nx.json or in plugin options, plus a check of nx show project output for a few representative projects. These figures are assumed for illustration, not measured. The real savings depend on how often such workspace-wide changes happen and how uniform your projects are.

The savings are partly offset by the costs described earlier: learning to inspect resolved configuration, diffing inferred targets across Nx upgrades, and the one-time migration work.

How do you keep the cache correct when inputs and outputs are inferred?

Once explicit targets are gone, the next risk is the cache itself, because inferred inputs and outputs are only as complete as what a plugin can read from a config file.

A plugin sees your static config, not what your build does at runtime. That leaves several common gaps:

  • Environment variables read via process.env inside a config or build script are invisible to the plugin.
  • Shared config imported from outside the project root, such as a base config in a tooling package, may not be hashed if only the project's own config file is listed.
  • Codegen output consumed by the build may not be tracked as an input.
  • Output directories computed at runtime may not be detected.

Missed inputs cause false cache hits, where Nx restores stale artifacts built against an old env value or base config. Missed outputs are quieter: the task reports a cache hit and replays its logs, but nothing is restored to disk, and a downstream step fails or ships an empty directory.

Fix gaps once, in shared config. Define a named input in nx.json that covers the shared config files and the relevant env entries. Add it to targetDefaults for the inferred target name so every project with that target picks it up. Use a project-level override for genuine one-offs, such as a custom output path. Check whether your Nx version merges or replaces inferred arrays. If you aren't sure, restate the full list.

To verify that outputs are declared correctly:

  1. Run the target.
  2. Delete its output directory.
  3. Run it again and confirm Nx restores the files.
  4. Diff the restored files against a fresh build run with --skip-nx-cache.

To verify inputs, change the env var or the shared file and confirm the next run is a cache miss.

What are the alternatives to inferred tasks?

Inference is one of several ways to define tasks in an Nx workspace, and they can be combined:

  • Explicit project.json targets with executors or commands. Every target is written out in the project. This is the most visible option and easy to grep and review, but it duplicates paths and options that already live in tool configs, and the duplication grows with the number of projects.
  • package.json scripts. Nx can run scripts defined in a project's package.json as targets. This works well for projects that already have scripts and need little Nx-specific configuration, though inputs and outputs for caching still have to be declared somewhere.
  • targetDefaults in nx.json. Shared settings such as dependsOn, cache, inputs and outputs can be applied by target name across the workspace. This reduces repetition for explicit targets without any plugin, but it doesn't create targets by itself.
  • A custom inference plugin. For internal tools no official plugin covers, you can write your own, as described in the next section.
  • Not using workspace-level task orchestration. Running each tool directly through package manager workspace scripts avoids Nx configuration entirely, at the cost of the project graph, affected-based runs and computation caching.

The table at the end of the next section compares the Nx-based options.

When should you write your own createNodes plugin, and when should you avoid inferred tasks?

A custom plugin pays off when the same internal tool runs in many projects: a codegen step, a Docker image build, or a Go or Python toolchain. Without one, each project carries a near-identical target, and a flag change means editing dozens of files. A small plugin keyed on a marker file turns that into one change in one place.

Pseudocode sketch (not a real API signature):

  1. Match every **/codegen.yaml.
  2. For each match, take its directory as the project root.
  3. Parse only that file and emit a codegen target with the command, inputs of the YAML plus the schema files it names, and outputs of the generated directory.

Plugins run during project graph computation, so a slow or nondeterministic plugin slows or destabilises every Nx command. Read only the matched files. Avoid network calls, timestamps and spawning the tool itself. Return the same targets for the same file contents. Any file the target depends on must appear in its inputs; otherwise edits will not invalidate the cache.

Limit inference when you have only a handful of projects, when no maintained plugin exists for the tool, or when nobody will own upgrades to an in-house plugin across Nx releases. If graph computation becomes noticeably slower, inference is costing you more than it saves.

Approach Boilerplate Visibility Maintenance cost Best fit
Explicit project.json targets High Fully visible in file Low per project, grows with count Few projects, one-offs
targetDefaults Low Split across files Low Shared options for named targets
Official plugins Minimal Requires nx show project Tracks Nx upgrades Supported tools
Custom plugins Minimal Requires nx show project You own it Internal tools at scale

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 inferred tasks, 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.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

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.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • 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.