What is a shared proto library in an Nx monorepo, and why make codegen a cached target?

A shared proto library is a single Nx project that owns your .proto files, along with buf.yaml (module and lint configuration) and buf.gen.yaml (which plugins run and where their output goes). Every gRPC client and server stub in the workspace is derived from that project by running buf generate. Nobody edits generated files by hand, and nobody copies them between services.

The pattern addresses three problems that show up once several services share schemas:

  • Consistent clients. Every consumer builds against the same schema revision and the same plugin configuration, so two services cannot drift onto subtly different stubs for the same RPC.
  • Rebuilds only on real change. Codegen becomes an Nx target whose inputs are the proto sources and the Buf config files. If neither has changed, Nx skips the run.
  • Faster CI. When a remote cache is configured, generated output is restored from the cache instead of regenerated on every agent and every pull request.

This approach fits backend and platform teams running a grpc monorepo where at least two or three projects consume the same schemas. With a single consumer, the extra setup is harder to justify.

A typical layout has a libs/proto project holding the sources and Buf config. Output goes to separate projects, such as libs/proto-go and libs/proto-ts, or to one dedicated generated-code library.

The split matters for cache correctness. If generated files land inside the source project, they can end up counted among that project's inputs. Generation then changes the inputs it just hashed, which invalidates its own cache. Keeping the output in a separate project with a separate boundary gives Nx a clean rule to work with: the inputs are the protos and config, and the outputs are everything in the generated directory.

+--------------------------------------+
| libs/proto   (source boundary)       |
|  *.proto   buf.yaml   buf.gen.yaml   |
+--------------------------------------+
                   |
                   | inputs: protos + Buf config (hashed)
                   v
+--------------------------------------+     +---------------------+
| Nx target: codegen (buf generate)    |<--->| Nx cache            |
| hit:  restore outputs from cache     |     | (local or remote)   |
| miss: run buf, store outputs         |     +---------------------+
+--------------------------------------+
         |                      |
         | outputs              | outputs
         v                      v
+------------------+   +------------------+
| libs/proto-go    |   | libs/proto-ts    |   output boundary
| generated stubs  |   | generated stubs  |   (separate projects)
+------------------+   +------------------+
         |                      |
         | imported by          | imported by
         v                      v
+------------------+   +------------------+
| Go services      |   | TS services      |
+------------------+   +------------------+

The libs/proto project owns the schemas and Buf config that Nx hashes as codegen inputs. Generated stubs go to separate output projects, so generation never changes its own inputs, and on a cache hit Nx restores the outputs instead of running buf.

Who should use cached proto codegen in Nx?

This setup is aimed at teams that already run, or plan to run, an Nx monorepo containing several gRPC services or clients that share schemas. Concretely, it fits when most of the following are true:

  • Several consumers share the same protos. Two or more services, an API gateway, or a frontend using generated TypeScript clients all import types from the same schema set.
  • Schemas change regularly. Protos are edited as part of normal feature work, not just a few times a year, so regeneration and the "did everyone regenerate?" question come up often.
  • More than one language is generated. Go servers with TypeScript clients, for example, each need their own plugin and output directory, and keeping them in step by hand is error-prone.
  • CI runs many jobs or agents. Restoring generated output from a shared cache is most useful when the same generation would otherwise repeat across jobs and pull requests.
  • A platform or developer-experience owner exists. Someone has to own plugin pinning, the Buf config and cache write permissions.

It is a weaker fit for a single service with its own protos, for schemas that live in a separate repository and are consumed as published packages, and for teams that are not using Nx for anything else. The section on when to avoid this approach covers those cases in more detail.

How does it work, end to end?

The mechanism has four parts: a source project, a cached generate target, declared dependencies, and the cache itself. A typical change flows like this:

  1. A developer edits a .proto file in the shared proto library, for example adding a field to a message in libs/proto.
  2. A consumer task is requested, such as nx build payments-service, or CI runs nx affected. Because the consumer's build declares dependsOn: ["^generate"], Nx schedules the proto library's generate target first.
  3. Nx hashes the generate target's inputs. These are the .proto files, buf.yaml, buf.gen.yaml, buf.lock, any toolchain pin file, the command itself, and runtime inputs such as a plugin's --version output.
  4. On a cache miss, Nx runs buf generate. Buf reads buf.gen.yaml, runs each pinned plugin, and writes stubs to the configured output directories. Nx then stores the files listed in outputs, plus the terminal output, under that hash in the local cache. If a remote cache is configured and the machine is allowed to write, the entry is uploaded too.
  5. On a cache hit, which happens when nothing that feeds the hash has changed, Nx skips buf generate entirely. It restores the stored output files and replays the logs, from the local cache or from the remote cache populated by another machine.
  6. The consumer task runs against the generated code that is now on disk. Its own cache key includes inputs inherited from its dependencies, so a schema change also invalidates the consumers that depend on it.
  7. Graph edges limit the blast radius. nx affected uses the project graph to select only the proto library and the projects that depend on it. Unrelated services are not rebuilt or retested.

Correctness depends entirely on step 3. Nx can only invalidate the cache for things it hashes, so every factor that changes generated output must be declared as an input. The next section covers how that hashing works and where it commonly breaks.

How does Nx decide when to rerun buf generate?

Before running generate, Nx computes a hash from everything declared as the task's inputs. These include the file sets you list (directly or through namedInputs such as a shared protos set), the task's command and options, inputs inherited from dependency projects, and any runtime or env entries. A runtime input runs a shell command and hashes its output. An env input hashes the value of an environment variable. If the hash matches a previous run, Nx does not invoke buf generate. It restores the files listed in outputs and replays the terminal output, either from the local cache or from a remote cache shared across machines and CI.

Ordering and scope come from the project graph. dependsOn makes a consumer's build wait for the proto library's generate. Graph edges decide which projects count as affected when a .proto file changes, so only downstream clients rebuild.

The weak point is that Nx hashes only what you declare. The common failure has three causes:

  • Locally installed plugins. A plugin such as protoc-gen-go on PATH is invisible to the hash. Upgrade it and Nx will still restore output from the old version unless a runtime input captures the plugin's version.
  • Remote plugins. If buf.gen.yaml references a remote plugin without pinning a version, the generator can change while the hash stays the same.
  • Buf dependencies. Leave buf.yaml and buf.lock out of the inputs, and changes to imported modules never invalidate the cache.

In each case the restored code compiles cleanly but no longer matches what buf generate would produce today. Pin plugin versions and list every config file as an input.

How do you define a cacheable generate target in project.json?

Start with buf.gen.yaml at the proto project root. Under the plugins key, give each plugin an exact pinned version (a remote reference with a version suffix, or a local binary you install at a fixed version) and an out directory such as gen/ts. Field names differ between buf config versions (v1 and v2), so check yours before copying anything.

In project.json, define a namedInputs entry, for example protoSources, that lists:

  • {projectRoot}/**/*.proto
  • {projectRoot}/buf.yaml
  • {projectRoot}/buf.gen.yaml
  • {projectRoot}/buf.lock
  • any toolchain file that pins local plugin binaries

The generate target uses the nx:run-commands executor with command: "buf generate" and cwd set to the project root. Set cache: true and set inputs to protoSources plus a runtime input such as { "runtime": "protoc-gen-ts --version" }. Nx runs that command and hashes its output. When a plugin upgrade changes only what is on PATH and no tracked file, the version string still changes, so the cache key changes too.

Set outputs to exactly {projectRoot}/gen. If you list {projectRoot}/src/gen while buf writes to gen/, Nx reports a cache hit but restores nothing. Consumers then fail to compile on a fresh CI agent, even though the build works locally. If you list {projectRoot}, a restore overwrites the whole project directory, including hand-written helpers and a newer buf.yaml. Keep generated code in a directory you never edit by hand. Confirm the inputs, outputs and runtime syntax against your Nx version's documentation.

{
  "name": "proto",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "projectType": "library",
  "namedInputs": {
    "protoSources": [
      "{projectRoot}/**/*.proto",
      "{projectRoot}/buf.yaml",
      "{projectRoot}/buf.gen.yaml",
      "{projectRoot}/buf.lock",
      "{projectRoot}/plugin-versions.txt"
    ]
  },
  "targets": {
    "generate": {
      "executor": "nx:run-commands",
      "cache": true,
      "inputs": [
        "protoSources",
        { "runtime": "protoc-gen-ts --version" }
      ],
      "outputs": ["{projectRoot}/gen"],
      "options": {
        "command": "buf generate",
        "cwd": "libs/proto"
      }
    }
  }
}

A project.json for a proto library at libs/proto: a cacheable generate target that runs buf generate, hashes protos, buf config and a runtime plugin version, and caches only the gen directory; plugin-versions.txt is a placeholder toolchain file.

Wiring consumers, lint and breaking-change checks into the project graph

Consuming services need generated code before they compile, so add "dependsOn": ["^generate"] to their build, typecheck and test targets. The ^ prefix tells Nx to run generate in the service's dependencies first. When the proto library's inputs haven't changed, that step is a cache hit and costs almost nothing.

^ only works if Nx knows the dependency exists. Nx can infer edges from TypeScript imports, but generated Go or Python packages, or path aliases into a gen/ directory, may not create one. In those cases, declare "implicitDependencies": ["proto-payments"] in each consumer's project.json. This edge also drives nx affected, so a missing edge means a proto change can skip a service that should have rebuilt.

Lint and breaking checks as separate targets

Define lint (running buf lint) and breaking (running buf breaking --against '.git#branch=main') as their own targets. Set their inputs to the .proto files and buf.yaml only, and leave buf.gen.yaml out, because changing a plugin setting can't change lint results. Be careful when caching breaking. Its baseline is a git ref that isn't part of the hash, so a cached pass can go stale after main moves. Either add the baseline commit as an input or disable caching for that target.

In CI, run nx affected -t lint breaking generate build test. A proto edit then fans out only to the library and its declared consumers.

Debugging

If generated output looks wrong, rerun with --skip-nx-cache to tell whether the problem is a stale cache entry or the generator itself. Then use nx show project <name> to check the resolved inputs. An input that is missing there means edits to it never change the hash, so Nx keeps restoring the old output.

{
  "name": "proto-payments",
  "root": "libs/proto-payments",
  "targets": {
    "generate": {
      "executor": "nx:run-commands",
      "options": { "command": "buf generate", "cwd": "libs/proto-payments" },
      "inputs": [
        "{projectRoot}/**/*.proto",
        "{projectRoot}/buf.yaml",
        "{projectRoot}/buf.gen.yaml"
      ],
      "outputs": ["{projectRoot}/gen"],
      "cache": true
    },
    "lint": {
      "executor": "nx:run-commands",
      "options": { "command": "buf lint", "cwd": "libs/proto-payments" },
      "inputs": ["{projectRoot}/**/*.proto", "{projectRoot}/buf.yaml"],
      "cache": true
    },
    "breaking": {
      "executor": "nx:run-commands",
      "options": {
        "command": "buf breaking libs/proto-payments --against '.git#branch=main,subdir=libs/proto-payments'"
      },
      "inputs": ["{projectRoot}/**/*.proto", "{projectRoot}/buf.yaml"],
      "cache": false
    }
  }
}

The shared proto library's project.json defines generate, lint and breaking as separate targets. Lint leaves buf.gen.yaml out of its inputs, and breaking has caching turned off because its main-branch baseline is not part of the task hash.

Should you commit generated gRPC code or gitignore it?

That stale entry is also why the commit-or-ignore decision matters. Either way the generate target stays cached. What changes is whether git or Nx is the source of truth for the files between runs.

Concern Commit generated code Gitignore generated code
Nx caching Cache hits restore files already in the tree, mostly a no-op Cache is the only fast way to get the files back
IDEs and language servers Imports resolve right after clone Imports are unresolved until generate runs
Review noise Proto changes come with large generated diffs Reviewers see only .proto changes
Hand edits and merge conflicts Edits can drift silently, and generated files conflict Edits cannot be committed, and there are no conflicts
Fresh clone, no cache Builds without buf installed Needs buf and every plugin before anything compiles
CI without warm remote cache Generate runs once in the guard job Generate runs in every job that needs consumers

If you commit the code, CI needs a guard. The job regenerates with --skip-nx-cache, then runs git diff --exit-code on the output directories. Skipping the cache is deliberate. A cache hit replays stored output, so it can hide a plugin upgrade that your inputs don't capture. The diff check catches three problems: someone edited a proto but didn't regenerate, someone hand-edited generated code, or the generator itself changed behaviour.

If you gitignore the code, you need a bootstrap step. Every consumer target that reads generated code (build, test, lint, typecheck) must list the proto project's generate target in dependsOn. Developers also need one documented command that runs generate across the workspace after cloning, so their editor has something to index.

How should you lay out multi-language generation and proto project boundaries?

One target with many plugins, or one target per language

A single generate target whose buf.gen.yaml lists every plugin is the least configuration you can have. However, Nx caches at the target level. All outputs share one cache entry, so bumping the Go plugin version also invalidates and regenerates the TypeScript client. Splitting into generate-ts and generate-go targets, each with its own buf.gen.yaml as an input, keeps those cache entries independent. The cost is extra templates and dependsOn wiring to maintain.

Choice Cache granularity Config cost Affected scope on change
One target, all plugins One entry for every language Low Every language's output
Per-language targets One entry per language Medium Only the language whose plugin changed
One proto project Shared Low Every consumer on any .proto edit
Several proto projects Per domain High Only consumers of the edited domain

The same trade-off applies to project boundaries. With one shared proto project, editing billing.proto marks the inventory service as affected, which widens CI runs. Splitting protos by domain narrows the affected set, but cross-domain imports then become explicit graph edges that you have to keep acyclic.

Verifying the setup

  1. Run the generate target twice. The second run should report a cache hit and restore outputs without invoking buf.
  2. Touch a .proto file and rerun. It should miss.
  3. Change a plugin version in buf.gen.yaml. It should also miss. If it hits instead, the template is missing from the target's inputs.
{
  "name": "proto",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "namedInputs": {
    "protoSources": ["{projectRoot}/**/*.proto", "{projectRoot}/buf.yaml"]
  },
  "targets": {
    "generate-ts": {
      "executor": "nx:run-commands",
      "cache": true,
      "inputs": ["protoSources", "{projectRoot}/buf.gen.ts.yaml"],
      "outputs": ["{projectRoot}/gen/ts"],
      "options": {
        "cwd": "{projectRoot}",
        "command": "buf generate --template buf.gen.ts.yaml"
      }
    },
    "generate-go": {
      "executor": "nx:run-commands",
      "cache": true,
      "inputs": ["protoSources", "{projectRoot}/buf.gen.go.yaml"],
      "outputs": ["{projectRoot}/gen/go"],
      "options": {
        "cwd": "{projectRoot}",
        "command": "buf generate --template buf.gen.go.yaml"
      }
    },
    "generate": {
      "executor": "nx:noop",
      "dependsOn": ["generate-ts", "generate-go"]
    }
  }
}

A proto project.json that splits generation into per-language cached targets. Each target lists the shared .proto files plus only its own buf.gen..yaml template as inputs, so bumping the Go plugin version invalidates generate-go but leaves the generate-ts cache entry intact.*

How can it save engineering time?

Most of the time saved comes from removing manual coordination and the debugging that follows when it goes wrong. Faster codegen is a smaller part of it. The savings fall into a few categories:

  • No manual regeneration step. With dependsOn: ["^generate"] on consumer targets, building or testing a service regenerates stubs when needed and skips the step when nothing changed. Engineers don't have to remember which services need buf generate after a schema edit.
  • Less time chasing drift. Every consumer uses the same pinned plugins and the same schema revision. "Works on my machine" failures caused by a locally upgraded protoc-gen-go, or by a service built against a stale copy of the protos, mostly go away.
  • Shorter waits on unchanged schemas. When the protos and config haven't changed, local builds and CI jobs restore generated output from the cache rather than running every plugin. With a remote cache, a new CI agent or a freshly cloned workstation can restore output that another machine already produced.
  • Smaller CI runs. nx affected limits lint, generate, build and test to the proto library and its declared consumers. Pull requests that don't touch protos don't pay for schema-related work at all.
  • Earlier detection of incompatible changes. Running buf breaking as a target in the same pipeline flags removed fields or changed types during review, before they reach a deployed client. That is usually far cheaper than diagnosing a production deserialization failure.
  • Cleaner reviews if generated code is gitignored. Reviewers read only the .proto diff instead of scrolling past generated files.

Illustrative estimate, using assumed inputs only: a team of 10 engineers, each hitting one regeneration-related problem per month (a forgotten regenerate, a mismatched plugin version, or a stale local copy) that takes an assumed 1 hour to diagnose. That works out to roughly 10 engineer-hours per month in avoidable debugging. Add an assumed 5 local builds per engineer per day that would otherwise wait an assumed 30 seconds on generation, and the team waits about 25 minutes per day in total. These figures are not measurements. Substitute your own team size, incident frequency and generation time to see whether the setup cost described in the next section is justified.

When should you avoid this approach, and what are the alternatives?

The setup pays off only when several projects consume the same schemas and those schemas change often. It is not worth it for a single service, or for protos that change a few times a year, because the generate step is rarely the slow part of CI. It also fails without discipline about pinning. Remote plugins and modules make every build depend on the registry being available, and every upgrade becomes a coordinated change. An unpinned plugin or dependency reference lets the output change while the cache key stays the same, so Nx serves stale code and reports a hit.

Treat shared and remote cache entries as trusted build artifacts. A poisoned entry, or one stored under the wrong key, reaches every consumer that restores it. Restrict who can write to the remote cache, for example CI only, and keep developer machines read-only.

Approach Fits when Main cost
Committed code, no cache Few consumers, slow-moving schemas Noisy diffs, drift if regeneration is skipped
Separate schema repo publishing versioned packages Consumers live in other repos or release independently Release overhead, version skew between services
protoc in per-service build scripts One or two services, no shared tooling Duplicated plugin setup, inconsistent output

Illustrative estimate, using assumed inputs: 40 CI runs per day, a 3-minute generate step, and an 80% cache hit rate. That saves about 96 CI minutes per day. Against that, assume 2 engineer-days of setup and 2 hours per month spent on plugin and pin upgrades. If engineer time costs far more than CI minutes, the setup recovers its cost only when the saved minutes also shorten feedback loops that engineers are actively waiting on.

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 protobuf codegen, 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.