How does Nx build an inferred target from plugins, targetDefaults and project.json?

Nx resolves a project's targets by applying several layers in order. Each layer can add a target or change fields on a target that an earlier layer created.

Layer 1: plugins

Each entry in the plugins array of nx.json scans the workspace for the tool configuration files it recognizes. A Vite plugin looks for Vite config files, and a Jest plugin looks for Jest config files. When a plugin finds a match, it creates targets for the project that owns that file. The plugin decides the command, inputs, outputs and caching from the tool config and from the options you pass to it. Plugins run in the order they are listed, so two plugins that produce a target with the same name will collide. The later plugin's fields take precedence.

Layer 2: targetDefaults

targetDefaults in nx.json are applied next. They are keyed by target name or executor. They are useful for workspace-wide settings such as dependsOn or shared inputs, which the plugin did not set or which you want to override everywhere.

Layer 3: project files

Explicit entries in a project's project.json, or in the nx field of its package.json, merge last. They override matching fields and leave the rest in place.

Why you should inspect the result first

Because of this layering, the target you actually run often isn't written down in any single file. Its command may come from a plugin reading vite.config.ts, its dependsOn from nx.json, and one option from project.json. If you read these files one at a time, you have to merge them in your head and get the precedence right. It is more reliable to look at the merged result first and then trace each field back to the layer that set it.

+-------------------+      +--------------------------------------------+
| vite.config.ts    |----->| Layer 1: plugins (nx.json "plugins" array) |
| jest.config.ts    |      |  run in listed order; each creates targets |
+-------------------+      |  command, inputs, outputs, cache           |
                           |  same target name: later plugin wins       |
                           +---------------------+----------------------+
                                                 |
                                                 v
+-------------------+      +--------------------------------------------+
| nx.json           |----->| Layer 2: targetDefaults                    |
|  targetDefaults   |      |  keyed by target name or executor          |
+-------------------+      |  e.g. dependsOn, shared inputs             |
                           +---------------------+----------------------+
                                                 |
                                                 v
+-------------------+      +--------------------------------------------+
| project.json  or  |----->| Layer 3: project files (merge last)        |
| package.json "nx" |      |  override matching fields, keep the rest   |
+-------------------+      +---------------------+----------------------+
                                                 |
                                                 v
                           +--------------------------------------------+
                           | Resolved target (the one Nx runs)          |
                           |  command   <- plugin reading vite.config.ts|
                           |  dependsOn <- nx.json targetDefaults       |
                           |  options   <- project.json                 |
                           |  not written down in any single file       |
                           +--------------------------------------------+
                                                 ^
                                  inspect here first, then trace back

Nx builds each target in three ordered layers: plugin inference from tool config files, then nx.json targetDefaults, then project.json or package.json overrides, so the resolved target is the only place where every field appears together.

What does nx show project tell you, and who should reach for it first?

nx show project <project-name> prints the configuration Nx will actually execute for that project. This is the result after plugins have inferred their targets, targetDefaults have been applied, and project.json or package.json overrides have been merged. For each target you see the executor or command, options, named configurations, inputs, outputs, dependsOn and caching behavior. If a field shows up here, Nx will use it. If it doesn't, Nx won't, no matter what you meant to write in nx.json.

Add --json to print the full configuration to stdout as JSON. That makes it scriptable: you can pipe it to other tools, diff it, or save it as a CI artifact. Without that flag, the default output depends on your installed Nx version and environment. Some setups open an interactive project details view in the browser, and others print to the terminal. Run nx show project --help to confirm the default behavior and available flags in your version before you build anything on top of it.

This command is most useful to platform and backend engineers who own CI pipelines, build tooling or plugin configuration in nx.json. They are the people who get asked why a target exists, why it didn't run, or why its cache keeps missing.

Start with the resolved configuration because the source files only tell you what should happen. Plugins often decide which targets and options to create based on which config files exist in a project directory. If you read the plugin source, you have to reproduce that logic for one specific project by hand. The merged output already gives you the answer, so your job becomes explaining one concrete value instead of predicting all of them.

# Confirm flags and default output (browser vs terminal) for your installed Nx version
npx nx show project --help

# Print the fully resolved configuration for one project as JSON on stdout
npx nx show project my-api --json > my-api.resolved.json

# List every target Nx will run for this project, including plugin-inferred ones
jq '.targets | keys' my-api.resolved.json

# Inspect the merged definition of one target: command/executor, options,
# inputs, outputs, dependsOn and cache settings after targetDefaults and overrides
jq '.targets.build' my-api.resolved.json

# Answer one concrete question: what does Nx treat as this target's cache inputs?
jq '.targets.build.inputs' my-api.resolved.json

# Save a baseline, change nx.json or a plugin option, then diff the resolved output
npx nx show project my-api --json | jq -S . > before.json
# ... edit nx.json ...
npx nx show project my-api --json | jq -S . > after.json
diff before.json after.json

Using nx show project --json with jq to list a project's resolved targets, inspect one target's merged settings, and diff the effective configuration before and after a change to nx.json.

How do you query a project's resolved targets with jq?

Start with the target list. Running nx show project api --json | jq '.targets | keys' prints every target name Nx resolved for the api project, after plugins, targetDefaults and project.json have been merged. If a target you expected is absent here, no executor or cache setting is involved yet. The problem is upstream, in plugin registration or file matching, and the next section covers that.

When the target exists, pull out the single object you care about, for example jq '.targets.build'. Read the fields in order of how likely they are to explain unexpected behavior:

  • executor or command: is Nx running the tool you think it is, with the arguments you think?
  • options: check the working directory, config file paths and flags. Plugins often derive these from file locations, so a moved config file changes them quietly.
  • inputs and outputs: these decide cache hits and what gets restored. A missing input explains a stale cache. An overly broad one explains constant misses.
  • cache: confirm it is actually enabled for this target.
  • dependsOn: shows which upstream targets run first. It often explains "why did this build three other projects?"

Before you look, write down what you expected each field to contain. Comparing against a stated expectation turns vague suspicion into a specific mismatch.

To find which plugin produced a target, or which file contributed a value, look at the metadata Nx attaches to resolved targets. You can see it in the detail view or in the JSON. Field names and coverage vary between Nx versions, so inspect your own output with jq '.targets.build | keys' rather than assuming a particular field exists.

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

# Resolve the project once and reuse the JSON for every query.
nx show project api --json > /tmp/api-project.json

# 1. Every target Nx resolved after merging plugins, targetDefaults and project.json.
#    If the target you expect is missing here, look at plugin registration first.
jq '.targets | keys' /tmp/api-project.json

# 2. Pull out the fields that usually explain unexpected behavior for one target.
#    Fields that are not set come back as null.
#    Command-style targets may show their command under .options instead of top level.
jq '.targets.build | {
  executor,
  command,
  options,
  inputs,
  outputs,
  cache,
  dependsOn
}' /tmp/api-project.json

# 3. Compare against what you expected. Write the expectation down first.
#    Example: expect build to depend on upstream builds and to be cacheable.
jq -e '.targets.build.cache == true' /tmp/api-project.json \
  || echo 'build: cache is not enabled'
jq -e '.targets.build.dependsOn // [] | index("^build") != null' /tmp/api-project.json \
  || echo 'build: dependsOn does not include ^build'

# 4. List the keys your Nx version actually attaches to the target.
#    Look for a metadata-style key that records which plugin or file produced it,
#    then inspect that key directly instead of assuming its name.
jq '.targets.build | keys' /tmp/api-project.json

Saves the resolved api project as JSON once, lists its target names, extracts the fields of the build target that most often explain surprises, checks two stated expectations, and lists the target's keys so you can find whatever metadata your Nx version exposes.

How do you debug a missing or misconfigured inferred target?

Workflow 1: the target is missing

  1. Confirm the plugin is registered. Open nx.json and check that the plugin appears in the plugins array. A plugin that is installed but not listed infers nothing.
  2. Confirm the triggering file exists where the plugin looks. Plugins match on file patterns such as a tool's config file in the project root. A config in a subfolder or with an unexpected file name or extension may not match, so the plugin never runs for that project.
  3. Check for a renamed target. Many plugins accept options that set the target name. If someone set the test target name to unit, then test is gone and unit exists instead. Read the plugin's options in nx.json before assuming inference failed.
  4. Confirm Nx sees the project at all. Run nx show projects. If the project is not listed, the problem is project detection, not target inference.

Workflow 2: the target has wrong options, inputs or outputs

Take the resolved JSON from nx show project <name> --json. Compare each suspect field against project.json and the matching targetDefaults entry to find which layer set it.

Layer What it contributes Common surprise
Plugin inference Base command, inputs, outputs Values depend on what the plugin reads from the tool's config
targetDefaults Shared defaults by target name or executor Applies to targets you didn't expect it to
project.json Per-project fields Merges with the inferred target

A project.json target with the same name merges with the inferred target. It overrides only the fields it defines and does not replace the whole target. Fields you leave out still come from the plugin.

When two plugins infer the same target name, the order of the plugins array can decide which one wins. Change the order in a scratch branch and compare the output of nx show project before and after to confirm how precedence works in your workspace.

# Workflow 1: the 'test' target is missing on project 'myapp'

# 1. Is the plugin registered? Installed-but-unlisted plugins infer nothing.
jq '.plugins' nx.json

# 2. Does the triggering config file exist where the plugin looks?
#    (Example assumes a Vite-based setup with the config in the project root.)
ls apps/myapp/vite.config.*

# 3. Do the plugin options rename the target? Look for target-name options
#    in the plugin entry printed in step 1 (e.g. 'unit' instead of 'test').

# 4. Does Nx detect the project at all?
nx show projects | grep -x myapp || echo 'myapp not detected: project detection problem'

# Workflow 2: the 'test' target exists but has the wrong options, inputs or outputs

# Fully resolved target after inference, targetDefaults and project.json are merged
nx show project myapp --json | jq '.targets.test' > /tmp/resolved-test.json

# Layer: targetDefaults (keyed by target name or executor)
jq '.targetDefaults.test' nx.json

# Layer: project.json. Only the fields defined here override the inferred values.
jq '.targets.test' apps/myapp/project.json

# Compare one suspect field across layers to find which one set it
jq '.outputs' /tmp/resolved-test.json
jq '.targetDefaults.test.outputs' nx.json
jq '.targets.test.outputs' apps/myapp/project.json
# If neither layer defines it, the value came from plugin inference.

Shell commands that walk through both workflows: checking plugin registration, the triggering file, plugin options and project detection, then comparing the resolved target JSON against targetDefaults and project.json to find which layer set a field.

Why does my configuration change seem to do nothing?

Inferred targets are not read from disk each time you run a command. Nx runs each plugin's inference against the matching config files, caches the result keyed on hashes of the inputs the plugin declares, and builds the project graph from those cached results. The Nx daemon keeps that graph in memory and updates it as files change. This is why commands feel fast, and also why an edit can appear to be ignored. If a change isn't picked up by the file watcher, or touches something the plugin's cache key doesn't cover (an environment variable, a file the tool reads indirectly, a plugin you just upgraded in node_modules), nx show project will report the old configuration.

After you change plugin options in nx.json or a tool config file such as a Vite, Jest or ESLint config, run nx reset before you trust the output. It stops the daemon and clears the cached workspace data, so the next command recomputes inference from scratch. If the target looks different after a reset, you were looking at stale state.

If you suspect the daemon itself, for example because the output changes between runs with no edits, rerun the command with NX_DAEMON=false. Nx then computes the graph in the foreground process. If the problem disappears, focus on the daemon.

Use both only while diagnosing a problem. nx reset also deletes the local task cache, so every task runs from scratch afterward. Leaving the daemon off means each command recalculates the project graph, and in a large workspace that cost is added to every invocation.

How can nx show project become a CI guardrail against silent target changes?

Inferred targets have a failure mode that hand-written configuration doesn't: they can change without any edit to your repository's project files. If someone bumps a plugin version, adds an entry to the plugins array, or changes a tool's own config file that a plugin reads, the resolved targets can shift silently. You can turn nx show project into a check that catches this before it reaches a production build.

Commit a small script that runs nx show project <name> --json for a short list of critical projects, such as the deployable services and the shared libraries everything depends on. For each project, the script reduces the output to target names plus the few fields your team relies on: the executor or command, dependsOn, outputs, and whether caching is enabled. It writes that reduced view to a checked-in snapshot file. In CI, the script regenerates the snapshot and fails if it differs from the committed copy. A plugin upgrade that renames a target or drops an output then shows up as a reviewable diff in the pull request.

Keep the parsing shallow. Read named keys under targets and ignore everything else. The surrounding JSON shape is not a contract, and a script that walks deep metadata will break on Nx upgrades for reasons unrelated to your builds.

Limit the check to a handful of projects. Dumping full JSON for every project in a large monorepo is slow and produces diffs nobody reads.

The trade-off favors keeping the script. It is a few dozen lines, and you will occasionally need to update the snapshot on purpose. That costs far less than tracing a deploy that stopped producing artifacts after a routine dependency update.

When should you avoid relying on nx show project, and what are the alternatives?

nx show project reports the merged result, not the reasoning behind it. When a plugin infers a target from a config file, the output tells you which inputs, outputs and options it chose. It does not tell you why the plugin picked a cache input or skipped a target entirely. For that, you still need the plugin's documentation or its source. The JSON shape and any metadata attached to it are also not a stable contract across Nx versions, so pin your CI snapshot script to the Nx version you run and expect to revisit it during upgrades.

Different questions call for different tools:

Question Better tool Why
Why does task A run before task B? nx graph or the project detail view Shows dependsOn chains across projects, which a single project's JSON cannot
Why did the plugin infer this option? Plugin source code The inference logic lives in the plugin's code, not in the output
What exactly will this project run? Fully explicit project.json No merge step, so nothing is hidden
What did all the layers resolve to? nx show project Shows the final merged view

Be careful with the middle ground. A project.json that overrides two options on an inferred target forces readers to hold three layers in their heads: plugin defaults, targetDefaults, and the override. That is harder to reason about than either a fully inferred or a fully explicit configuration. It also brings back the per-project configuration that inference was meant to remove. If a project needs many overrides, make it fully explicit. If it needs few, change the plugin options or targetDefaults instead.

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 show project, 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.