Why doesn't the Nx project graph see proto and schema dependencies?
Nx keeps a project graph: one node per project and one directed edge for every "depends on" relationship. Most edges come from static analysis. Nx parses JavaScript and TypeScript files for import and require statements, reads package.json dependencies, and resolves each target to the project that owns it. Plugins can add more edges through the graph extension API. This is how language plugins teach Nx about Go modules, Gradle builds and other ecosystems.
nx affected uses that graph. It maps changed files to the projects that own them, then walks the edges backward to find every dependent. A project with no inbound edges has no dependents.
This is why proto and schema definitions get missed. A service imports generated stubs, such as a TypeScript client, a Go package or a Python module. It never imports the .proto or JSON Schema file those stubs came from. The import scanner sees an edge to the generated code, or no edge at all if the stubs are written into the service's own directory. It sees nothing that points back to the protos project. You can change a field number or rename an RPC, and nx affected will report that only the protos project changed. Every consumer that should be rebuilt and retested gets skipped.
implicitDependencies fixes this. It is a list of project names in a project's configuration, and each entry becomes a graph edge with no import behind it. The edge is checked into the repo, so changes to it show up in code review. Backend and platform teams that run affected-based CI in a protobuf monorepo, or that share schema files across services, need it.
One prerequisite applies to polyglot repos. A Go, Java or Python consumer must be registered as an Nx project before any edge can point to it. You can do that with an explicit project.json or with a plugin that infers the project. Nx cannot draw an edge to a directory it doesn't treat as a project.
Nx project graph (arrow = "depends on", consumer --> dependency)
+---------------------+ codegen, no import +----------------------+
| protos | - - - - - - - - - - - -> | generated stubs |
| user.proto, *.json | (no graph edge) | TS / Go / Python |
+---------------------+ +----------------------+
^ ^
| implicitDependencies | import
| (explicit, in project config) | edge
| |
+----------+-------------------------------------------------+----------+
| consumer services (registered Nx projects) |
| orders-api (TS) billing (Go) reports (Python) |
+-----------------------------------------------------------------------+
nx affected: changed file -> owning project -> walk edges backward
without implicitDependencies: edit user.proto => only protos affected
with implicitDependencies: edit user.proto => protos + consumers
+----------------------------------+
| Go / Java / Python code that is | not a graph node, so no edge
| not registered as an Nx project | can point to or from it
+----------------------------------+
Consumers import only the generated stubs, so the only path from a .proto or schema change to them is an explicit implicitDependencies edge, which can exist only for code registered as an Nx project.
How do you declare nx implicitDependencies for a protos project?
Take a layout with three projects: libs/protos holding the .proto files, and apps/orders-service and apps/billing-service, which compile against stubs generated from them. Start by giving libs/protos its own project.json with "name": "protos". Without it, Nx assigns a changed .proto file to no project, or to a root project if you have one. A change that belongs to no project affects nothing. A change assigned to the root project is too broad to be useful. Once protos is a real project, its default inputs ({projectRoot}/**/*) already include every definition file. If you want targets such as lint or generate to hash only the definitions, add a named input like "protoFiles": ["{projectRoot}/**/*.proto"] and reference it in those targets' inputs.
Each consumer then declares the edge in its own project.json as "implicitDependencies": ["protos"]. Projects defined through package.json use the same array under the nx key: "nx": { "implicitDependencies": ["protos"] }.
The dependent lists what it depends on. orders-service names protos, and protos does not name orders-service.
The backwards version looks harmless but breaks the graph. Suppose you put "implicitDependencies": ["orders-service", "billing-service"] in the protos project.json. That creates edges from protos to the services. Now edit orders.proto and run nx affected -t test. Only protos is reported, so neither service's tests run, even though its generated stubs just changed. The reverse case also misfires: a change inside orders-service now marks protos as affected. The result is under-testing where you need coverage and wasted work where you don't.
# libs/protos/project.json: make the .proto files belong to a real project.
cat > libs/protos/project.json <<'EOF'
{
"name": "protos",
"namedInputs": { "protoFiles": ["{projectRoot}/**/*.proto"] },
"targets": {
"lint": {
"inputs": ["protoFiles"],
"command": "protoc --proto_path=libs/protos --descriptor_set_out=/dev/null libs/protos/*.proto"
}
}
}
EOF
# Correct direction: the dependent (orders-service) names what it depends on.
cat > apps/orders-service/project.json <<'EOF'
{
"name": "orders-service",
"implicitDependencies": ["protos"]
}
EOF
# billing-service is defined via package.json, so the same array goes under "nx".
cat > apps/billing-service/package.json <<'EOF'
{
"name": "billing-service",
"nx": { "implicitDependencies": ["protos"] }
}
EOF
# A .proto change should now run tests for protos, orders-service and billing-service.
nx affected -t test --files=libs/protos/orders.proto
# WRONG (do not do this): this line in libs/protos/project.json creates edges
# protos -> services, so the command above would test only protos:
# "implicitDependencies": ["orders-service", "billing-service"]
The protos project gets its own project.json with a .proto-only named input. Each consumer declares implicitDependencies on protos, in project.json or under the nx key in package.json, so editing a .proto file marks both services as affected.
How do exclusions and glob patterns work in implicitDependencies?
When static analysis infers an edge that does not reflect a real runtime or build relationship, you can remove it. In implicitDependencies, an entry prefixed with ! tells Nx to drop a dependency it would otherwise infer. If a file in orders-service happens to import a path that resolves into protos, but protos should sit upstream, adding "!orders-service" to the protos project's implicitDependencies deletes the incorrect edge. Use this only to correct a specific, understood mistake. Each exclusion is a statement that the analyzer is wrong. Without a reason recorded next to it, the next engineer has no way to tell whether that statement still holds.
Glob patterns let one entry cover many projects. If every service under a naming convention consumes the shared schemas, an entry such as "*-service" in a consumer's list, or a set of explicit names in the protos project's dependents, saves you from editing configuration each time a service is added. The cost is that matching is implicit. A new project whose name happens to fit the pattern picks up the edge silently, whether or not it reads a single .proto file. Naming conventions drift, so treat a glob as a policy you have to maintain.
Both behaviors depend on your Nx version. Whether negation combines with globs, how wildcards match, and whether tag-based selectors are accepted have all varied between releases. Check the documentation for the version in your lockfile. After every change, run nx graph and confirm that the edges you expected exist and the ones you excluded are gone.
# 1) Exclusion: protos must stay upstream. A helper script inside protos
# references orders-service, so Nx infers protos -> orders-service.
# That edge is wrong. "!orders-service" removes it.
# JSON has no comments, so record the reason in your PR or a README.
cat > libs/protos/project.json <<'EOF'
{
"name": "protos",
"sourceRoot": "libs/protos/src",
"implicitDependencies": ["!orders-service"]
}
EOF
# 2) Glob: contract-tests exercises every service that follows the
# *-service naming convention. Any new project whose name matches
# picks up this edge automatically, whether or not it is a service.
cat > tools/contract-tests/project.json <<'EOF'
{
"name": "contract-tests",
"sourceRoot": "tools/contract-tests/src",
"implicitDependencies": ["protos", "*-service"]
}
EOF
# 3) Check the result against the Nx version you actually run.
npx nx --version
# Open the graph focused on protos. The protos -> orders-service edge
# should be gone, and contract-tests should have edges to every *-service.
npx nx graph --focus=protos
# Write the graph to a file so the edges can be reviewed in a diff.
npx nx graph --file=graph.json
Two project.json files: one uses a '!' exclusion to remove a wrong inferred edge from protos, and one uses a '-service' glob to depend on every matching service, followed by nx graph commands to check the resulting edges.*
How does codegen ordering and caching work alongside graph edges?
Edges in the project graph and the order in which tasks run are two separate concerns. The project graph decides what is affected. The task graph decides what runs first. An implicit dependency from orders-service to protos puts orders-service in the affected set, but it does not run code generation before the build.
Give the protos project a generate target. Then give consumer build targets a dependsOn entry: ^generate runs generate on every project this one depends on, including dependencies declared through implicitDependencies. If you want only one specific project to run first, use an explicit target reference instead.
Caching needs its own configuration. Define a named input on protos that covers {projectRoot}/**/*.proto and any schema files. Use that input for the generate target. Also include it in the input that consumers pull in through ^-prefixed inputs. This way a .proto edit changes the hash of generate and of every downstream build. Without this, Nx can replay a cached build that was compiled against the old contract.
| Concern | Configured by | Answers |
|---|---|---|
| Traversal | implicitDependencies |
Which projects are affected? |
| Ordering | dependsOn |
What runs before this task? |
| Cache keys | inputs, namedInputs |
Can a cached result be reused? |
Committed generated code needs extra care. Nx may infer an edge from consumers to the checked-in stubs because consumers import them. Nothing infers an edge from the definitions to the stubs. If someone edits a .proto file and does not regenerate, consumers build cleanly against stale stubs and the breakage stays hidden. Model that link explicitly, and add a CI check that regenerates the stubs and fails if the output differs from what is committed.
// nx.json: shared defaults for every project
{
"namedInputs": {
"default": ["{projectRoot}/**/*"],
"production": ["default"]
},
"targetDefaults": {
"build": {
// Ordering: run generate (and build) on dependencies first,
// including dependencies declared via implicitDependencies
"dependsOn": ["^generate", "^build"],
// Cache key: ^production pulls in each dependency's own
// production input, so a .proto edit changes this hash
"inputs": ["production", "^production"],
"cache": true
}
}
}
// libs/protos/project.json: the contract definitions
{
"name": "protos",
"namedInputs": {
// Overrides production for this project: only contract files
"production": ["{projectRoot}/**/*.proto", "{projectRoot}/schemas/**/*.json"]
},
"targets": {
"generate": {
"executor": "nx:run-commands",
"options": { "command": "./scripts/gen-protos.sh" },
"inputs": ["production"],
"outputs": ["{workspaceRoot}/libs/protos-generated"],
"cache": true
}
}
}
// apps/orders-service/project.json: traversal only, no import needed
{ "name": "orders-service", "implicitDependencies": ["protos"] }
Three Nx config files, shown with comments for annotation: implicitDependencies marks orders-service as affected, dependsOn runs generate before build, and the protos production named input makes .proto and schema edits change the cache hash of generate and of downstream builds.
How can you verify that the affected set is correct?
Graph edges are configuration, and configuration fails silently. Nothing breaks when an implicit dependency is missing; the affected set just shrinks, and CI skips projects it should have rebuilt. That is why the edges need a deliberate check.
Inspect the edges
Start with nx graph and select the definitions project. Every consumer that reads its .proto or schema files should appear as a dependent. Implicit edges are drawn the same way as inferred ones, so focus on which projects are connected rather than how the edges look. If a service that imports generated stubs is not connected, the declaration is missing or an exclusion pattern removed it.
Prove it with a real change
The visual check only shows what Nx believes. To confirm that this belief drives affected, make a change. On a scratch branch, edit a single .proto file, for example by adding a comment or a field. Then run nx show projects --affected against your main branch, using --base if your default base differs. Read the output in two passes:
- Every expected consumer is listed. A missing consumer means its changes will skip CI.
- Unrelated projects are absent. An overly broad glob is just as costly in CI time, and it hides the cases where a narrower edge was intended.
To see the tasks rather than the projects, view the task graph for an affected build.
Make it routine
Repeat this check whenever someone adds a new consumer, renames a project, or splits a definitions project into smaller ones. Manual edges do not update themselves when the code moves. Each of these changes can leave a stale or missing edge, and nothing will report it.
When should you avoid or limit implicitDependencies?
Every implicit edge is a claim that someone has to keep true by hand. When a service starts importing a new proto package and nobody adds the edge, nx affected skips it on the next schema change and the break shows up after merge. When a service stops using a package and the edge stays, it gets rebuilt and retested for nothing. Neither mistake produces a warning.
The opposite habit, pointing every service at one shared schemas project, removes the drift risk but costs a lot. Edges are project-level, so Nx cannot express "billing-service uses only payments.proto". Any change to any file in schemas marks every consumer as affected, which cancels most of what affected-based CI saves.
Splitting definitions into one project per package or domain reduces the blast radius. The cost is more projects, more edges to maintain, and more places for drift to happen.
Illustrative estimate. Assume 40 services, 8 domain proto packages with about 5 consumers each, and 6 minutes of build and test per service.
| Layout | Services affected by one proto change | CI work per change |
|---|---|---|
Single schemas project |
40 | 240 min |
| Split per domain | ~5 | ~30 min |
Neither layout guards the contract. An edge only tells Nx what to rerun. It does not check that a removed field or renumbered tag is safe for existing consumers. You still need backward-compatibility linting on the definitions themselves.
What are the alternatives to manual implicitDependencies?
Hand-written implicitDependencies are one of three ways to model these links. The other two change where the edge comes from rather than how it is written.
Finer-grained definition projects split one large protos project into several per-domain projects, such as billing and identity. Each consumer declares an edge only to the domain it uses, so a change to identity messages no longer marks billing services as affected. The edges are still manual, but each one is narrower. The cost is more project configuration and a decision about where shared message types live.
A local Nx plugin implements createDependencies and derives edges from a mechanical rule. For example, a rule might say "any project whose source imports from the generated output of project X depends on X." Edges then follow the code, and nobody has to remember to update a JSON file. The rule also lives in one reviewed, testable place instead of being copied across many project.json files. The cost is ongoing: the plugin needs its own tests, it adds work to graph computation, and it has to stay compatible with the plugin API across Nx upgrades.
| Approach | Drift risk | Review effort | Maintenance cost |
|---|---|---|---|
Hand-written implicitDependencies |
High as projects grow | Low, visible in diffs | Low |
| Finer-grained definition projects | Medium | Low to moderate | Moderate, more projects |
Local plugin with createDependencies |
Low, rule-derived | Higher, logic not data | Highest, tests and upgrades |
For a handful of edges, plain JSON is easier to audit than inferred logic. Switch to a plugin when many projects declare the same edge. Also switch when reviews keep catching missing edges, or when the rule can be stated precisely enough that a short function expresses it without special cases.
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
.envby 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.