What are Nx implicitDependencies and why does the project graph need them?

implicitDependencies is a list of project names you attach to a project to tell Nx "this project depends on those, even though you can't see it in the code." It is a manual override that adds edges to the project graph where source analysis has nothing to go on.

Nx infers most edges itself. It statically analyzes source files for imports that resolve to other workspace projects, such as TypeScript path aliases or package names. It also reads package.json dependency fields that reference other packages in the workspace. Language plugins can contribute edges the same way. All of this inference depends on a machine-readable reference: an import statement, a dependency entry, or something a plugin knows how to parse.

Coupling in backend and infrastructure code often has no such reference. Common cases include:

  • Reading another project's configuration files, such as a service that loads a shared YAML or JSON config at runtime or during its build.
  • OpenAPI or protobuf contracts that are consumed by a code generator, not imported directly.
  • SQL migrations whose schema an API's queries assume.
  • Docker build context that copies files from a sibling directory into an image.

Nx sees none of these, so a change to the contract or migration does not mark the consumer as affected. Treat each implicitDependencies entry as a documented claim: "this project breaks if that one changes, for a reason the graph cannot detect." Backend and platform engineers get the most from this. Their monorepos tend to hold contract, schema, and infrastructure projects that other projects depend on without ever importing them.

How do you declare implicitDependencies in project.json or package.json?

Declaration lives with the dependent project, not the dependency. In project.json, add a top-level implicitDependencies array of project names. For a project managed through package.json, put the same array inside the nx object of that file. Both forms produce the same edge, so pick the file that already acts as the project's source of configuration. Splitting configuration across both files makes it harder to see why the graph looks the way it does.

Edge direction

If project A lists project B, the graph gets an edge from A to B. A depends on B, so a change to B marks A as affected. This mirrors an ordinary import, and it determines where the entry belongs. The consumer declares what it relies on. The producer stays unaware of its consumers. For example, orders-api lists order-schema. order-schema lists nothing.

Excluding an inferred dependency

Prefixing a name with !, as in !legacy-utils, removes an edge that Nx would otherwise infer from source analysis. Use it when static analysis produces a false positive, such as a type-only import that you deliberately treat as non-binding. Treat every exclusion as a claim that you must be able to defend. You are hiding a link that the code itself suggests exists.

Patterns

Recent Nx releases accept glob-style patterns, such as shared-*, to match several projects by name. Exclusions combine with patterns. Pattern support, the exact syntax, and where implicit dependencies can be configured have changed between Nx releases. Check the documentation for the version pinned in your workspace before relying on a pattern.

# File: apps/orders-api/project.json
# The dependent project (orders-api) declares what it relies on.
# Edges point orders-api -> each listed project, so a change to
# order-schema or any shared-* project marks orders-api as affected.
{
  "name": "orders-api",
  "implicitDependencies": [
    "order-schema",
    "shared-*",
    "!legacy-utils"
  ]
}
# "shared-*"      glob pattern; confirm your Nx version supports it
# "!legacy-utils" removes an edge Nx would otherwise infer from source

# File: apps/orders-worker/package.json
# Same declaration for a project configured through package.json:
# the array goes inside the "nx" object.
{
  "name": "orders-worker",
  "version": "0.0.0",
  "nx": {
    "implicitDependencies": ["order-schema"]
  }
}

# File: libs/order-schema/project.json
# The dependency lists nothing. It does not need to know its consumers.
{
  "name": "order-schema"
}

Declaring implicitDependencies on the consuming project in project.json and in the nx field of package.json, with a plain project name, a glob pattern, and a '!' exclusion; the comments sit outside the JSON so each file stays valid as written.

How do implicit edges change nx affected and task ordering?

Once an implicit edge exists, Nx treats it like any edge inferred from imports. nx affected maps the changed files to the projects that own them, then walks the project graph to every project that depends on those projects, directly or transitively. If orders-api declares an implicit dependency on order-schema, a commit that only touches a JSON Schema file in order-schema marks orders-api as affected, even though no TypeScript import connects them. Anything that depends on orders-api is also marked affected, because the traversal does not distinguish implicit edges from inferred ones.

The same edges drive task ordering. A dependsOn entry of ^build in targetDefaults means "run build on this project's dependencies first." Implicit dependencies count as dependencies for this purpose. So when orders-api builds, Nx schedules order-schema:build ahead of it. That matters when the schema project generates types, validators, or a bundled contract that the service reads at build time. Without the edge, the two builds could run in parallel or in the wrong order, and the service would pick up stale or missing artifacts.

The cost is precision. An implicit dependency is project-to-project, not file-to-file. Editing a README, a test fixture, or a lint config inside order-schema still makes every dependent affected. In a workspace where one shared project has many consumers, a single trivial change can fan out into a large CI run. The computation cache can reduce the actual work when a task's input hash is unchanged, but the affected set itself stays wide, and that is what CI uses to decide which tasks to schedule.

# Config assumed in this example (shown as comments):
#
# apps/orders-api/project.json
#   { "name": "orders-api", "implicitDependencies": ["order-schema"] }
#
# nx.json
#   { "targetDefaults": { "build": { "dependsOn": ["^build"] } } }

# 1. Change only a non-code file in the schema project.
echo '  ' >> libs/order-schema/schemas/order.schema.json
git commit -am "touch order schema"

# 2. List affected projects. orders-api appears through the implicit
#    edge alone, because no TypeScript file imports order-schema.
#    Anything that depends on orders-api is listed too.
npx nx show projects --affected --base=main --head=HEAD

# 3. Build what is affected. ^build makes Nx schedule
#    order-schema:build before orders-api:build, so the service
#    reads freshly generated types and validators.
npx nx affected -t build --base=main --head=HEAD

# 4. The edge is project-to-project, not file-to-file. Editing a
#    README in order-schema still marks every dependent affected.
echo "Notes" >> libs/order-schema/README.md
git commit -am "docs only"
npx nx show projects --affected --base=HEAD~1 --head=HEAD
# orders-api and its dependents are listed again. A cache hit can
# skip the build work itself, but CI still schedules those tasks.

This example assumes that orders-api declares an implicit dependency on order-schema, and it shows three effects of that edge: a schema-only change marks orders-api as affected, ^build orders the two builds, and even a docs-only edit widens the affected set.

Worked example: a backend service consuming a shared schema project

Illustrative scenario, not a measured result. Assume a workspace with two projects. order-schema holds JSON Schema and OpenAPI YAML files and has no TypeScript entry point. orders-api is a Node service whose build step copies those files into its output and validates request bodies against them at runtime. No source file in orders-api imports anything from order-schema, so Nx's static analysis finds no edge between them.

Before: two disconnected nodes

orders-api · · · order-schema (no edge)

An engineer adds a required field to order.schema.json. In CI, nx affected -t build deploy sees one changed file, maps it to order-schema, and stops. The affected set is order-schema only. orders-api is not rebuilt or redeployed. Production keeps validating against the old schema, and the new field is silently rejected or ignored. Nothing in the pipeline fails, so no alert fires.

After: one declared edge

Adding "implicitDependencies": ["order-schema"] to the orders-api project configuration gives the graph:

orders-api ──depends on──▶ order-schema

The same schema-only change now produces the affected set order-schema, orders-api. If orders-api's build target uses dependsOn: ["^build"], Nx also schedules any order-schema build target before it, so the copied files are current.

Why this saves debugging time

In the first state, the defect surfaces as a runtime behavior bug, and someone has to work backward from production logs to a CI run that reported success. In the second state, the redeploy happens automatically. If it fails, CI shows the failure in the commit that changed the schema.

# Illustrative scenario: declare the non-code link from orders-api to order-schema.
# Static analysis cannot see this link because orders-api never imports order-schema.
cat > apps/orders-api/project.json <<'EOF'
{
  "name": "orders-api",
  "projectType": "application",
  "implicitDependencies": ["order-schema"],
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "dependsOn": ["^build"],
      "options": {
        "command": "node tools/build-orders-api.js"
      }
    }
  }
}
EOF

# Simulate a schema-only change on a branch.
git switch -c add-required-field
# (edit libs/order-schema/order.schema.json, then commit)
git commit -am "order-schema: add required field"

# List the affected set. Before the edit above this printed only order-schema;
# with the implicit dependency it should list order-schema and orders-api.
nx show projects --affected --base=main --head=HEAD

# Inspect the edge visually in the project graph.
nx graph --affected --base=main --head=HEAD

# CI now rebuilds and redeploys orders-api for schema-only commits.
nx affected -t build deploy --base=main --head=HEAD

Shows the orders-api project.json with an implicit dependency on order-schema and the Nx commands that confirm a schema-only change now pulls orders-api into the affected set (illustrative scenario, not a measured result).

When should you use namedInputs or sharedGlobals instead of implicitDependencies?

An implicit dependency answers one question: which project does this project depend on? Inputs and namedInputs answer a different one: which files contribute to a task's cache hash? They overlap, so they are easy to confuse.

When the real dependency is a single file, such as a root tsconfig.base.json, a shared lint config, or a lockfile, an edge to a whole project is too coarse. Every change in that project now marks your service as affected, and if the target uses ^ dependency inputs, those files enter its hash too. That causes cache misses you did not need. The opposite failure is worse. An edge does not by itself put the file you care about into the hash. If the target's inputs leave out ^-prefixed patterns, or the dependency's named input filters out the relevant file, Nx can return a stale cache hit even though the graph looks correct.

Put workspace-root configuration in sharedGlobals (referenced from the default named input) or in a targeted input on targetDefaults. Do not add an implicit dependency on a placeholder project to every consumer. This puts the file into the cache hash of every task that uses those inputs, without inventing graph structure.

Situation Better tool Why
Root config file affects many targets sharedGlobals / default named input Hashes the exact file, with no fake edges
One target reads a specific external file Target-level inputs Scoped to the task that reads it
Code uses another project's types or functions A real import Nx infers the edge from source
Several services share a schema or protocol An extracted contract package Makes the dependency explicit and importable
Runtime or deploy coupling with no file in common implicitDependencies No file-level signal exists
{
  "namedInputs": {
    "sharedGlobals": [
      "{workspaceRoot}/tsconfig.base.json",
      "{workspaceRoot}/babel.config.json"
    ],
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/jest.config.ts"
    ]
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/eslint.config.mjs"],
      "cache": true
    },
    "generate-client": {
      "inputs": ["{projectRoot}/codegen.config.json", "{workspaceRoot}/specs/orders-api.yaml"],
      "outputs": ["{projectRoot}/src/generated"],
      "cache": true
    }
  }
}

An nx.json that hashes root config files through sharedGlobals and the default named input, adds the lint config only to lint, and scopes an external API spec to the one target that reads it, so these file dependencies are tracked without adding implicitDependencies edges.

How do you verify the project graph instead of trusting it?

A declared edge is a claim about the repository, and Nx won't warn you if the claim is wrong. A misspelled project name in a glob pattern can match nothing. A plugin can infer targets and inputs that override what you expected. A version upgrade can change how project.json and package.json configuration are merged. Each of these fails silently: CI simply runs less than it should. Treat verification as part of the change, not an afterthought.

Check the edge exists

Run nx graph and focus on the consuming project. Confirm the edge to the shared project is present and points the right way. The dependent should point at the thing it depends on. If you used a pattern or a ! exclusion, look at the projects it actually resolved to rather than reading the configuration and assuming.

Check the resolved configuration

Run nx show project <name> to see the project after plugins, target defaults and inferred targets have been applied. The output in this command is what Nx will execute; your project.json alone is not. Look at three things:

  • Implicit dependencies: the declared list is present.
  • Target dependencies: the relevant targets declare dependsOn so upstream builds run first.
  • Inputs: each target's inputs include the files you expect to invalidate the cache.

Check affected behaves as intended

Make a throwaway commit that touches only the shared project. Then run nx affected against an explicit base, such as your main branch. The consuming service should appear in the affected set. If it doesn't, the graph is wrong, and fixing it now is cheaper than finding out after a stale deploy.

When should you avoid implicitDependencies, and how do you keep them maintainable?

Implicit edges fail silently. Nx never checks whether an edge still reflects reality, so a stale entry produces no error. If an edge outlives its reason, it over-triggers: every change to the source project rebuilds and retests a consumer that no longer cares. If a real link was never declared, or was declared against a project that has since been renamed, it under-triggers, and the break shows up later in a downstream build that affected skipped.

Patterns that cost more than they save

Pattern What goes wrong Better option
Wildcard (*) Every project depends on every other project, so affected becomes "run everything" Name the specific projects
! exclusion Hides a real import, so changes to that project stop triggering the consumer Remove the import, or keep the edge
Many edges to one config project Signals coupling through files instead of contracts Extract a package that projects import

If several projects need edges to the same set of files, treat that as an architectural problem. Don't keep adding entries. Turn the shared files into a project with a real entry point. Consumers can then import it, and Nx infers the edge.

Maintenance conventions

  • Put a one-line comment or README note next to each edge that says why it exists and which files create the link.
  • Review all implicit edges whenever a project is renamed, split, or deleted.
  • Prefer an explicit import or package dependency, and remove the manual edge once inference covers it.

These habits keep the affected set accurate. Accurate edges cut CI time because unrelated projects stop running. They also cut debugging time because a broken downstream build points to a real dependency, not a stale one.

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.
  • 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.