What problem do Nx implicitDependencies solve in the project graph?

Nx builds its project graph mostly by reading code. It parses source files for import and require statements, resolves them against workspace path mappings, and reads package manifests to find workspace packages that depend on each other. Language plugins can add edges for other ecosystems, but the principle is the same: an edge exists because a tool found a reference it understands. That graph drives everything downstream, including which projects count as affected by a change and the order in which tasks run.

Static analysis only sees what is expressed as code. Several couplings that platform teams deal with every day fall outside that:

  • A service that generates clients or validates requests from a shared OpenAPI document or .proto file that lives in another project.
  • An API that applies SQL files from a migrations project at startup or deploy time.
  • A Helm chart or Dockerfile project that packages the build output of another project.
  • An end-to-end suite that calls a deployed service over HTTP and never imports a line of its code.

In each case, changing one project can break another, and the graph does not show it. Affected detection skips the dependent project, and CI reports green on a change that should have failed.

implicitDependencies exists to declare a project-to-project edge that analysis cannot see, and nothing more. It is not a cache-tuning tool or a way to model file-level inputs. This article is for backend and platform engineers who own monorepo CI and are responsible for keeping the graph correct.

Who should use implicitDependencies?

Use implicitDependencies if you maintain an Nx workspace where projects are coupled at runtime, build time, or deploy time without importing each other. In practice that usually means one of these roles:

  • Platform and CI owners who are responsible for nx affected runs and need the affected set to match what can actually break.
  • Teams that own contract projects, such as OpenAPI specs, protobuf definitions, JSON schemas, or SQL migrations, where consumers read the files instead of importing a module.
  • Teams that own end-to-end suites that exercise a running service over the network.
  • Teams that own packaging or deployment projects, such as Docker images or Helm charts, that wrap another project's build output.

The condition is the same in every case. There is a specific project on each side of the link, and the link is invisible to Nx's analysis.

You probably don't need it in these situations:

  • All couplings are imports or workspace package dependencies. Nx already sees those edges.
  • The thing you depend on is a root-level file, such as a lockfile, base tsconfig, or CI script, rather than a project. Use task inputs for these, as described below.
  • A language plugin already infers the edge for that ecosystem. Check the graph before adding a manual entry.

How does implicitDependencies work, and which way does the edge point?

Here is how it works in brief. You list project names in a project's configuration. Nx adds those names as graph edges during project graph construction. Affected detection and task ordering then treat those edges exactly like edges inferred from code.

implicitDependencies is an array of project names in a project's configuration. For each name, Nx adds an edge to the project graph from the declaring project to the named project, the same edge it would add if it had found an import. The declaring project is always the dependent. Writing "implicitDependencies": ["api"] in api-e2e's project.json says "api-e2e depends on api." It says nothing about api depending on api-e2e.

Take three projects. contracts holds shared request and response types. api imports them, so Nx detects that edge from source. api-e2e sends HTTP requests to a running api and never imports it, so Nx cannot see that link. Declaring it closes the gap:

api-e2e ──▶ api ──▶ contracts

Affected detection walks these edges backwards. It starts from each changed project and marks everything that depends on it, directly or transitively:

Changed project Affected set Why
contracts contracts, api, api-e2e api imports contracts, and api-e2e depends on api
api api, api-e2e the implicit edge points from api-e2e into api
api-e2e api-e2e nothing depends on api-e2e

The last two rows show why direction matters. Editing an e2e spec does not rebuild or retest the API, because the API's behavior did not change. Editing the API does rerun the e2e suite, because those tests check that behavior.

If you reverse the declaration and put api-e2e in api's list, both outcomes flip. That is wrong in both cases.

{
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "name": "api-e2e",
  "projectType": "application",
  "sourceRoot": "apps/api-e2e/src",
  "implicitDependencies": ["api"]
}

apps/api-e2e/project.json declares the link to api, which adds the edge api-e2e ──▶ api so that a change to api (or to contracts) marks api-e2e as affected, while a change to api-e2e leaves api unaffected.

How do implicit edges change affected detection and task ordering?

Direction matters because both of Nx's downstream behaviors read the same edges.

Affected detection

When you run an affected command, Nx maps each changed file to the project that owns it, then walks the graph toward dependents and marks each one affected. Implicit edges are part of that walk. Detection works at the project level, not the file level: any change inside the upstream project triggers the dependent, whether it is a schema the dependent actually reads, a README, or a test fixture. Nx has no way to tell which files mattered because the link carries no import information. That is why broad edges get expensive. Point a shared config project at every service, and almost every pull request rebuilds and retests everything.

Task ordering

The same edge changes execution order. If a target's dependsOn contains the caret form, as in "dependsOn": ["^build"], Nx runs build on every project this one depends on first, and that includes implicit dependencies. Three problems follow from this:

  • Unnecessary waiting. An e2e project with implicit edges to several apps waits on all of their builds, even when the tests only need one deployed artifact.
  • Cycles. If an implicit edge closes a loop that already exists through imports, the task graph contains a cycle and the run fails. It does not pick an order.
  • Hidden fan-out. An edge you added for affected detection also adds build steps to the critical path of every caret-based target.
{
  "name": "checkout-e2e",
  "projectType": "application",
  "implicitDependencies": ["checkout-web", "api-gateway"],
  "targets": {
    "e2e": {
      "executor": "nx:run-commands",
      "dependsOn": ["^build"],
      "options": {
        "command": "node scripts/run-e2e.js",
        "cwd": "apps/checkout-e2e"
      }
    }
  }
}

An e2e project.json where implicit edges to checkout-web and api-gateway make any file change in either app mark checkout-e2e affected, and "^build" makes e2e wait for both builds.

When should you use implicitDependencies instead of inputs or namedInputs?

The rule of thumb: an edge says "this project's code depends on that project's code"; an input says "this task's output depends on this file." Most non-code links are the second kind. Root config files, the lockfile, a shared .env.example, and CI scripts are not owned by any project, and they usually affect many projects at once. They belong in task inputs. A common workaround is to create a placeholder project around them and point implicitDependencies at it. That makes the graph noisy and still doesn't change the cache hash the way you intend.

The usual pattern is a namedInputs entry in nx.json, for example sharedGlobals, that lists paths such as {workspaceRoot}/tsconfig.base.json and {workspaceRoot}/ci/*.sh. The default named input then includes sharedGlobals, and targetDefaults references default. If your nx.json still has a top-level implicitDependencies map keyed by file path, it comes from an older workspace layout. Move those entries into inputs.

The two layers fail independently. Affected detection walks the graph, but the cache key is built from inputs. If a file is missing from a task's inputs, Nx can mark the project affected, compute an unchanged hash, and replay a stale cached result. The run looks green even though the change was never tested.

Mechanism Granularity Maintenance Failure mode
Explicit implicitDependencies edge Whole project Manual list per project Over-building, hidden fan-out
Named input File glob per task One place in nx.json Missing glob causes a stale cache hit
Custom inference plugin Derived from file contents Code you own and test Plugin bug silently drops edges
{
  "namedInputs": {
    "sharedGlobals": [
      "{workspaceRoot}/tsconfig.base.json",
      "{workspaceRoot}/.env.example",
      "{workspaceRoot}/ci/*.sh"
    ],
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts"
    ]
  },
  "targetDefaults": {
    "build": {
      "cache": true,
      "inputs": ["production", "^production"]
    },
    "test": {
      "cache": true,
      "inputs": ["default", "^production"]
    }
  }
}

An nx.json where root-level files live in a sharedGlobals named input that default includes, so editing them changes every build and test cache hash without creating placeholder projects or implicitDependencies edges.

When should you avoid implicitDependencies or the '!' negation form?

Hand-written edges have no feedback loop. When a shared schema file moves or a service stops reading a generated config, the implicitDependencies entry stays put and nothing fails. The graph keeps an edge that no longer reflects reality, every change to the upstream project marks the downstream one as affected, and CI runs work it doesn't need. Each stale entry costs little, but the cost accumulates, and nobody notices until someone asks why a one-line change triggered half the pipeline.

The opposite failure is worse. When a new non-code coupling appears and nobody declares it, affected detection leaves the dependent project out. Its tests don't run, its build is skipped, and the breakage surfaces after merge. An over-approximated graph wastes money. An under-approximated one ships bugs.

The ! negation form

Prefixing a project name with ! removes an edge that Nx inferred, usually from import analysis. Teams reach for it when an import is type-only, sits in dead code, or exists for tooling that never runs in production. Use it rarely, and put a comment or commit message next to each entry that says why the edge is false. If the analysis was actually correct, the negation hides a real dependency. You get missed tests and cache hits that replay stale outputs, and it looks like Nx is working as intended.

Placeholder projects

Don't create empty projects whose only purpose is to anchor edges to a shared folder. They clutter the graph, they have no meaningful owner, and they hide which team is responsible for the files that actually changed.

// apps/billing-api/project.json
// Nx parses project.json leniently, so // comments are accepted here.
{
  "name": "billing-api",
  "projectType": "application",
  "implicitDependencies": [
    // Non-code link: billing-api loads JSON schemas from
    // libs/shared-schemas at startup. Nothing imports them, so Nx
    // cannot infer this edge.
    // Re-check this entry whenever the schema loading code changes.
    // A stale entry fails silently and only costs CI time.
    "shared-schemas",

    // Negation: removes the edge Nx inferred from an import of
    // pdf-renderer. The only import is `import type` in
    // src/legacy/export.ts, which is dead code and slated for removal.
    // If that file is revived or the import becomes a value import,
    // delete this line. Otherwise billing-api will miss affected runs
    // and get cache hits that replay stale outputs.
    "!pdf-renderer"
  ]
}

A project.json that declares one non-code edge Nx cannot infer and negates one inferred edge, with comments that record why each entry exists and when to remove it.

What are the alternatives when a hand-written list stops scaling?

The distinction is identity. If a directory of OpenAPI specs, protobuf definitions, or JSON schemas has an owner, a review process, and work that runs against it, promote it to a minimal project. Give it a project configuration and nothing else at first. It now appears as a real node in the project graph, and consumers can depend on it by name instead of pointing at a path. More importantly, it can carry its own targets: lint the schemas, check for breaking changes, generate client stubs. Those targets have their own inputs and cache entries, so a schema change triggers validation once, at the source, rather than relying on every consumer's tests to catch the problem indirectly.

Contributing edges from a plugin

The second alternative applies when the links follow a rule. Suppose every service reads configuration from a folder named after the service. You end up writing the same implicitDependencies entry over and over, and someone eventually forgets it. A custom Nx plugin can encode the rule instead. During graph construction it inspects the workspace, matches each service to its folder, and returns the dependency edges. New services pick up the correct edge automatically, and the convention is enforced in one place.

The cost is real. The plugin is code your platform team owns, tests, and upgrades alongside Nx. It also runs while the graph is computed. A bug can silently drop edges and cause missed affected detection. A slow filesystem scan adds latency to every command, for every developer and every CI job.

How can implicitDependencies save engineering time?

Correctly scoped implicit edges save time in three places.

Fewer post-merge breakages to debug. A missing edge means a change to a schema, migration, or service merges without running the tests that would have caught it. The cost then shows up later as a broken main branch, a failed deploy, or a bug report. Someone has to bisect commits to find a cause that a correct graph would have flagged in the pull request. Declaring the edge moves that failure back into the PR, where the author still has the context to fix it.

No need for "run everything" safety nets. Teams that don't trust the graph often add workarounds: a nightly full run, a manual "run all e2e" label, or a CI rule that skips affected detection for certain paths. Those workarounds cost machine time and waiting time, and someone still has to triage what fails. When the graph contains the real non-code links, affected runs can be the default and the workarounds can be retired.

Narrower runs when the edges are precise. A single edge to the one project that actually matters, instead of a placeholder project or a broad edge to shared config, keeps the affected set small. That has a direct effect on CI duration and on how long developers wait for feedback.

Illustrative estimate (assumed numbers, not a measurement). Time saved per month from catching a breakage in the PR instead of after merge = escaped breakages per month × (assumed hours to diagnose and fix after merge − assumed hours to fix in the PR).

With an assumed 4 escaped breakages a month caused by an undeclared e2e or schema link, an assumed 3 hours each to diagnose and fix after merge, and an assumed 0.5 hours to fix when caught in the PR: 4 × (3 − 0.5) = 10 engineer-hours per month. Your inputs will differ. The structure of the calculation is the useful part: savings scale with how often non-code links break and how expensive late discovery is in your organization.

These savings depend on the edges staying accurate. A stale or over-broad edge turns the same mechanism into a cost, which is why the verification steps below matter.

How do you verify implicit dependencies and keep CI costs honest?

Each implicitDependencies entry is a claim about runtime coupling, so it needs a test. Begin with nx graph: focus on the project you changed and confirm the new edge appears and points from the consumer to the thing it depends on. Then run nx show project <name> to see the resolved configuration, including merged implicitDependencies. This catches typos, glob patterns that matched nothing, and ! negations that removed more than you intended.

The graph can look correct and still be wrong. Add a CI check that simulates a known change. List affected projects for a fixed file, such as nx show projects --affected --files=<path>, and assert that the expected dependent is in the output. Add a negative assertion too: an unrelated project must not appear. The positive check guards against missed tests. The negative check guards against wasted CI time.

Illustrative estimate (assumed numbers, not a benchmark). Wasted CI minutes per week = PRs per week × share of PRs touching the source project × extra projects pulled in × minutes per project.

With 200 PRs, 30% touching a shared config project, an over-broad edge adding 40 projects, and 3 minutes each: 200 × 0.3 × 40 × 3 = 7,200 minutes per week. Remote caching lowers the real cost, but only for projects whose inputs did not change.

PR review checklist

  • Does the edge point from the dependent to its dependency?
  • Is there a concrete runtime or build reason for the edge, written in the PR description?
  • Do the affected assertions cover both an expected project and an excluded project?
  • If the PR removes an edge, does a test still fail when the formerly linked project breaks?

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.