Why do non-code assets go missing from the Nx project graph?

Nx constructs most of its project graph by reading code. For TypeScript and JavaScript it parses source files and resolves import and require statements to the project that owns the target path. Language plugins do the equivalent for their ecosystems, and package.json dependencies between workspace packages add further edges. Every edge in the graph traces back to something Nx can statically analyze.

Backend services often depend on files that no import statement ever names. A gRPC service runs a codegen step against .proto files in a shared directory. A migration runner reads .sql files from a path in its configuration. An API gateway loads OpenAPI or JSON Schema documents with a file read at startup. A worker parses .yaml routing rules that another team maintains. In each case the reference is a string path passed to a compiler, a CLI flag, or a filesystem call. Nx does not interpret these strings, so it never connects the consuming project to the project that owns the asset.

The missing edge has two consequences. First, nx affected will not select the consuming service when someone changes a shared schema, so CI skips its tests and builds. Second, the asset is usually outside the service's own inputs, so its build hash does not change and Nx can restore a cached artifact produced from the old schema. Both failures produce a passing pipeline.

This guide is for backend and platform engineers who run services in an Nx monorepo and rely on nx affected and the task cache to keep CI fast without missing changes.

What are nx implicitDependencies in project.json?

implicitDependencies is a property in a project's project.json that lists other projects this one depends on, even though no import statement says so. Nx builds most of its graph by analysing source files. This property lets you add the edges that analysis cannot see. Each entry becomes a dependency edge in the project graph, and Nx treats it like any inferred edge when it calculates affected projects and orders tasks.

The minimal case is a single line. In apps/orders-api/project.json, alongside name and targets, you add "implicitDependencies": ["shared-protos"]. This tells Nx that orders-api depends on shared-protos, so a change inside shared-protos should mark orders-api as affected. You do not touch any TypeScript or build config.

The array also accepts a negated form, "!project-name". This removes an edge that Nx inferred. It is useful when static analysis picks up a false dependency, such as a type-only import from a package that never affects runtime behaviour. Every exclusion hides a real or apparent coupling from nx affected, so leave a written reason in the pull request or in a nearby README. A bare ! entry with no explanation is how a team stops testing a service that actually needed it.

Two properties of these entries cause most of the trouble:

  • They are project names, not file paths. "libs/shared-protos" or "protos/*.proto" does not point Nx at a directory. The value has to match the name of a project Nx already knows about.
  • They are plain strings. Nothing rewrites them when a project is renamed. Depending on how the reference fails, Nx may raise an error or the edge may quietly stop meaning what you intended.
{
  "name": "orders-api",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "apps/orders-api/src",
  "projectType": "application",
  "implicitDependencies": [
    "shared-protos"
  ],
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "options": {
        "command": "echo build orders-api"
      }
    }
  }
}

A minimal apps/orders-api/project.json that adds a manual graph edge to the shared-protos project by name, so changes there mark orders-api as affected.

How do you implement the asset-project pattern?

Give the asset folder its own project.json, even if it only declares a name and tags. Once Nx finds that file it treats the folder as a project, so files under libs/shared-protos or db/migrations belong to a graph node. Without it, edits to those files do not map to any project. Tags such as type:asset and scope:orders cost nothing at runtime. They make asset projects easy to filter in the graph view and let module-boundary lint rules treat them differently from code libraries.

A target is optional but often worth adding. For example, a validate target can lint the .proto files, or a generate target can emit client stubs. With a generate target in place, the asset owns the step that turns raw files into something consumers can import.

On the consumer side, list the asset's project name in implicitDependencies. Then add dependsOn: ["^generate"] to the consumer's build target. The caret tells Nx to run generate on each dependency before the consumer builds, so stubs exist when compilation starts. If the asset project has no generate target, the caret matches nothing and Nx skips it without complaint. A typo in the target name fails the same way: the build proceeds against stale output.

Avoiding cycles

Keep generated output flowing in one direction. A cycle appears when the asset's generate target needs something from a consumer, for example reading a consumer's config or depending on its build. Declaring that edge makes the asset depend on its own dependent. Nx cannot order tasks in a cycle and will refuse to run them. Move any shared input into the asset project itself.

# Asset project: a name and tags make libs/shared-protos a graph node.
# The generate target is where raw .proto files become importable stubs.
cat > libs/shared-protos/project.json <<'EOF'
{
  "name": "shared-protos",
  "tags": ["type:asset", "scope:orders"],
  "targets": {
    "generate": {
      "executor": "nx:run-commands",
      "options": { "command": "node tools/gen-protos.mjs libs/shared-protos" }
    }
  }
}
EOF

# Consumer: implicitDependencies adds the graph edge that code imports cannot.
# "^generate" runs generate on each dependency first. If a dependency has no
# target with exactly that name (missing or misspelled), Nx silently skips it.
# Never make shared-protos depend on orders-api. That edge would create a cycle.
cat > apps/orders-api/project.json <<'EOF'
{
  "name": "orders-api",
  "tags": ["type:app", "scope:orders"],
  "implicitDependencies": ["shared-protos"],
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "dependsOn": ["^generate"],
      "options": { "command": "tsc -p apps/orders-api/tsconfig.app.json" }
    }
  }
}
EOF

# Runs shared-protos:generate first, then orders-api:build.
npx nx run orders-api:build

An asset project with its own project.json and generate target, plus a consumer that declares it in implicitDependencies and uses dependsOn ["^generate"] so stubs are generated before the build.

How does affected detection propagate from an asset change?

Nx answers "what is affected?" in two steps. First, it diffs the working tree against a base ref and maps each changed file to the project whose root contains it. Second, it walks the project graph in reverse, marking every project that depends on an owner, directly or transitively. During that walk, Nx makes no distinction between edges inferred from imports and edges you declared with implicitDependencies. That is why a .proto edit can reach services that never import a TypeScript or Go file from shared-protos.

git diff base...head
        │
        ▼
libs/shared-protos/orders.proto ──► owner: shared-protos
                                          │
                     ┌────────────────────┴───────────────────┐
                     ▼  (implicit edge)                        ▼  (implicit edge)
                 orders-api                                billing-api
                 [affected]                                [affected]

If either service has its own dependents, such as an e2e project, those dependents are marked affected too. Projects with no path to shared-protos are left out of the run.

Before you trust this in CI, confirm three things locally:

  • Run nx graph and check that the edges from orders-api and billing-api to shared-protos actually appear. A typo in a project name shows up here, or Nx rejects it outright.
  • Change a .proto file, then run nx show projects --affected with the same --base and --head your pipeline uses. The output should list shared-protos, orders-api and billing-api, and nothing unexpected.
  • Run nx affected -t test to confirm that the targets which run are the ones you expected, not only the projects that were selected.
#!/usr/bin/env bash
# Check locally that a .proto edit selects the expected projects
# before relying on affected detection in CI.
set -euo pipefail

# Use the same refs as the pipeline. With both --base and --head set,
# Nx diffs committed history (base...head), so the change must be committed.
BASE=origin/main
HEAD_REF=HEAD

# 1. Inspect the graph. The interactive view opens in a browser.
#    The JSON export lets you check the edges from a script.
npx nx graph --file=graph.json
jq '.graph.dependencies["orders-api"], .graph.dependencies["billing-api"]' graph.json
# Each list should contain an entry with target "shared-protos".

# 2. Commit a throwaway .proto change on a scratch branch.
git switch -c check/proto-affected
echo '// affected-detection check' >> libs/shared-protos/orders.proto
git commit -am "test: touch orders.proto"

# 3. List the selected projects. Expect shared-protos, orders-api, billing-api,
#    plus any of their dependents (for example, e2e projects). Nothing else.
npx nx show projects --affected --base="$BASE" --head="$HEAD_REF"

# 4. Run the target to confirm which tasks actually execute, not only which
#    projects were selected. A project with no test target is skipped here.
npx nx affected -t test --base="$BASE" --head="$HEAD_REF"

# Clean up the scratch branch.
git switch -
git branch -D check/proto-affected

A local check script that exports the project graph to confirm the implicit edges to shared-protos, commits a test edit to a .proto file, then runs nx show projects --affected and nx affected -t test with the same base and head refs as CI.

Does implicitDependencies affect the Nx cache hash?

An implicitDependencies entry adds an edge to the project graph and nothing else. Affected detection walks that graph, so orders-api is selected when shared-protos changes. The cache works differently. It hashes each task from the target's inputs, and those inputs decide whether files from shared-protos count at all.

Dependency-relative inputs such as ^production or ^default tell Nx to include the matching file sets from every project upstream in the graph, including implicit dependencies. With those, editing a .proto file changes the orders-api:test hash and forces a real run. If a target uses narrow custom inputs, such as only {projectRoot}/**/* plus a few config files, the edge still makes orders-api affected. However, the hash ignores the protos and matches the previous run. Nx then replays the cached result, which was computed against the old contract. That is a false pass with no warning.

Configuration Affected selection Cache hash Task ordering
implicitDependencies with ^production or ^default inputs Includes dependents Changes when asset files change Unchanged unless dependsOn uses ^
implicitDependencies with narrow custom inputs Includes dependents Ignores asset files, so stale hits are possible Unchanged unless dependsOn uses ^
Adding dependsOn: ["^build"] No effect by itself No effect by itself Runs the asset project's build first, if it defines one

Don't assume which inputs apply, because target defaults and plugins can override them. Run nx show project orders-api to see the resolved inputs, or add --json for machine-readable output. Then check each target's inputs for a ^ entry that covers the asset files.

#!/usr/bin/env bash
# Confirm the graph edge exists, then check whether each target's resolved
# inputs actually pull upstream (^) files into the task hash.
set -euo pipefail

PROJECT=orders-api

# 1. The graph edge: should list shared-protos. This drives affected selection only.
nx show project "$PROJECT" --json | jq '.implicitDependencies'

# 2. Resolved inputs per target, after target defaults and plugins are applied.
nx show project "$PROJECT" --json \
  | jq '.targets | to_entries[] | {target: .key, inputs: .value.inputs}'

# 3. Flag targets whose inputs list no ^-prefixed string entry.
#    Such a target is still selected as affected when protos change, but its
#    hash ignores them, so it can replay a stale cached result.
#    Object-form inputs that reference dependencies are not checked here;
#    review any flagged target by hand.
nx show project "$PROJECT" --json | jq -r '
  .targets | to_entries[]
  | select(.value.cache == true)
  | select([(.value.inputs // [])[] | strings | select(startswith("^"))] | length == 0)
  | "WARN: \(.key) has no ^ input; changes in shared-protos will not change its hash"
'

A shell check that uses nx show project --json and jq to confirm the implicit dependency edge, print each target's resolved inputs, and flag cacheable targets with no ^-prefixed input that would leave shared-protos files out of the cache hash.

What are the alternatives to implicitDependencies, and when should you avoid them?

The lighter alternative is a file-glob input on the one target that reads the asset. Adding {workspaceRoot}/config/shared/**/* to orders-api:build inputs means edits to those files change that target's hash and force a re-run. It adds no node or edge to the project graph, though. nx graph won't show the relationship, and whether nx affected picks up the change depends on how your Nx version maps workspace-root files to projects. Use inputs when you care about cache correctness for one target, and an edge when the relationship should be visible and drive affected runs.

Older workspaces may still carry a top-level file-to-project mapping in nx.json (also named implicitDependencies). Newer guidance replaced it with inputs. Check the docs for your installed version before you keep it, remove it or migrate it.

Approach Precision Graph effect Hash effect Maintenance
implicitDependencies in project.json Project-level Adds an edge Dependents rehash via ^ inputs Low, but easy to over-link
Glob inputs on one target File- and target-level None Direct Per target, globs can drift
Legacy nx.json file mapping File-to-project Version-dependent Version-dependent Migrate away

Avoid edges in these cases:

  • One catch-all asset project. If a single broad shared-config project is linked to everything, any edit marks everything affected. Split it by consumer.
  • Negating correct edges. Using !project to silence a real import hides a dependency that should stay in the graph. Remove the import instead.
  • Assets used only outside the workspace. Dockerfiles, deployment manifests and files fetched at runtime aren't read by Nx targets, so an edge only triggers rebuilds that test nothing relevant.
  • Replacing contract tests. An edge tells you a consumer should be rechecked. It doesn't tell you the consumer still works.

How do these edges affect CI cost and engineering time, and how do you verify them?

Every edge is a cost decision. Over-linking (pointing one large shared-config project at every service) widens the blast radius, so a one-line change rebuilds and retests services that never read the file. Splitting assets into narrower projects reduces that waste, but each split is another project.json someone has to own and keep accurate. Under-linking is the expensive failure because it is silent. CI goes green, or Nx replays a stale cache hit, and the broken service ships anyway.

Illustrative estimate (assumed numbers, not a benchmark): wasted CI minutes per asset change = (linked projects − projects that actually read the asset) × minutes per project pipeline. With 12 linked, 3 real consumers and 8 minutes each, that comes to (12 − 3) × 8 = 72 minutes per change.

Asset-only projects also clutter run-many output and project lists. Give them a consistent tag such as type:asset so people and scripts can tell them apart, and use your module-boundary lint constraints to stop code projects from importing them as libraries. Require every PR that adds an edge to say which file the consumer reads at build, test or runtime. If the author can't name one, the edge probably shouldn't exist.

Regression checklist

  1. On a branch, change one asset file.
  2. Confirm the expected services appear in the affected list, and nothing unexpected appears with them.
  3. Confirm the downstream task hash changed and the next run is a cache miss.
  4. Confirm the deploy jobs driven by affected output pick up the service.

Run the checklist again whenever project names, folder layouts or input globs change. Those are the changes that break edges without any error.

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 implicitDependencies, 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.