Monorepo Build Systems Explained: Build Graphs, Caching and Affected Targets

Every pull request, a proposed change waiting for review, waits for work that has nothing to do with it. In CI, the continuous integration servers that build and test every change, a one-line fix still rebuilds and retests every other app and library. Monorepo build systems exist to stop that waste without letting broken code through.

Picture a common setup. One git repository holds a small online shop: a storefront web app, an orders API and a shared utils library that formats prices in rupees. The web app imports utils; the API does not. CI builds and tests all three on every pull request, and as the repository grows that reaches 40 minutes per run (made up). The setup is made up, but this slowdown is a common one in a growing monorepo.

In a setup like this, people start batching changes to dodge the wait. A flaky test in one package blocks merges in another. Much of the CI time goes into rebuilding code that did not change since yesterday.

A monorepo build system fixes this with three ideas. A graph tells it what depends on what. A cache lets it skip work it has already done. Affected-target selection tells it which parts a change can touch at all. This guide builds each idea on the shop example, then checks it on real tools.

Keeping git itself fast at this size, with huge histories and many contributors, is a separate problem with its own guide on monorepo version control. This guide is only about builds and tests.

Nine words carry the whole topic. Each one is used the same way for the rest of the guide.

• Package: one folder with its own package.json, such as apps/web. Nx calls it a project. Bazel splits code into smaller named targets declared in BUILD files.
• Task: one command for one package, such as build for apps/web. Turborepo and Nx both use this word.
• Dependency: a package that another package imports. In the shop, utils is a dependency of web.
• Dependent: the same link read the other way. The web app is a dependent of utils.
• Hash: a fixed-length fingerprint computed from data. Change one byte of the data and the fingerprint changes completely.
• Cache hit and cache miss: a hit means a saved result matched the fingerprint and was reused. A miss means the task had to run.
• Artifact or output: a file a task produces, such as the bundled dist folder of the web app.
• Base branch: the branch your change is compared against, usually main.
• Lockfile: the file that pins the exact versions of outside packages, such as package-lock.json for npm.

Monorepo build systems are task runners that understand the whole repository. They read how packages depend on each other, run tasks in the right order, skip tasks whose inputs have not changed, and select only tasks a change can affect. A plain script runs everything every time; these tools decide what to run.

The three well-known open-source tools do the same four jobs at different levels of detail. The table compares them on what this guide tested or sourced, as of 27 October 2026.

The build graph is a directed graph: each package is a box, and each arrow means needs this first. The tool starts every box with no unfinished arrows at once, up to its concurrency limit (Turborepo's default is 10 tasks, as of 27 October 2026). A box starts as soon as everything it needs has finished.

In Turborepo you describe the arrows once in turbo.json. The caret in ^build means my dependencies' build tasks must finish first. The outputs line lists the files a build produces, which matters for caching later.

{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

We ran this on the shop repository with turbo 2.11.10 and npm workspaces, npm's built-in way to link the packages of one repository. Each build script was padded to take 1.5 seconds, standing in for a real compile. The utils and api builds started together, and web started only after utils finished.

Nx drew the same graph from the same package.json files. Its graph output listed web depending on utils, and api and utils depending on nothing. Bazel builds a finer graph: it parses every BUILD file into targets and the actions that produce them. Its unit is one compiler call, not one package.

The graph already saves time, because independent packages run in parallel. The longest chain of arrows, here utils then web, sets the minimum time. Nx 24.0.2 prints this as the critical path at the end of each run.

The tool builds a key from everything that can change a task's output, looks that key up, and either restores the saved output or runs the task and saves it. Content-addressed means data is stored and found by a hash of its content, not by a file name or a date. Two machines with identical inputs compute the same key.

Strictly, the key is computed from the inputs. Bazel then stores each output file under the hash of its own bytes. Turborepo and Nx keep each task's outputs together under the task's key; our .turbo/cache held one archive per hash.

The key usually covers four things. The command and the tool configuration. The contents of every input file. The values of declared environment variables. And the hashes of the tasks it depends on, which is why a change in utils reaches web.

Bazel's open Remote Execution API spells this out. It uses the word digest for a hash plus the data's size. An action is identified by the digest of its encoded form, which includes the digests of the command and of the whole input file tree. The action cache maps that digest to a result. The content-addressable store, or CAS, keeps each output file under the hash of its own bytes.

Think of a tailor's order book. Each finished order is filed under the exact measurements, fabric and design. When a new order matches an old entry exactly, the tailor hands over a copy of the finished shirt instead of stitching again. Measurements, fabric and design are the inputs, the entry number is the hash, and the shirt is the output.

Where the picture breaks: a tailor cannot copy a shirt for free, but a cache copies outputs at almost no cost. And the tailor only checks what was written in the book. If your arm grew but nobody measured it, you get the old shirt. That is exactly how wrong cache hits happen.

The whole mechanism fits in a short Python script. It runs a shell command, keys it by command, declared environment and input file contents, and keeps outputs in a dictionary that plays the CAS. The build reads two files but declares only one.

import hashlib, json, os, subprocess, tempfile

cas, action_cache = {}, {}  # cas maps a digest to bytes; action_cache maps a key to an output digest

def digest(data):
    return hashlib.sha256(data).hexdigest()

def run_action(cmd, inputs, env):
    """cmd: list of args, inputs: list of file paths, env: dict of declared env vars."""
    key_parts = {"cmd": cmd, "env": sorted(env.items()),
                 "inputs": {p: digest(open(p, "rb").read()) for p in sorted(inputs)}}
    key = digest(json.dumps(key_parts, sort_keys=True).encode())
    if key in action_cache:
        return "HIT", cas[action_cache[key]].split()
    out = subprocess.run(cmd, capture_output=True, env={**env, "PATH": os.environ["PATH"]}).stdout
    cas[digest(out)] = out                     # store the bytes by their own hash
    action_cache[key] = digest(out)            # remember: this action made those bytes
    return "MISS", out.split()

d = tempfile.mkdtemp()
src, extra = os.path.join(d, "price.txt"), os.path.join(d, "tax.txt")
open(src, "w").write("499\n"); open(extra, "w").write("18\n")
build = ["sh", "-c", f"cat {src} {extra}"]     # reads tax.txt, but we only declare price.txt

print(run_action(build, [src], {"MODE": "prod"}))   # MISS: first time
print(run_action(build, [src], {"MODE": "prod"}))   # HIT: same key
os.utime(src, (0, 0))                                # change only the timestamp
print(run_action(build, [src], {"MODE": "prod"}))   # HIT: content, not time, is hashed
print(run_action(build, [src], {"MODE": "dev"}))    # MISS: declared env is in the key
open(extra, "w").write("28\n")                       # change the UNDECLARED input
print(run_action(build, [src], {"MODE": "prod"}))   # HIT with stale output: 18, not 28

On Python 3.13.17 the five calls printed MISS, HIT, HIT, MISS and HIT. The last line still printed 499 and 18, not 28. The cache did exactly what it was told, and the answer was stale.

What just happened? Changing only the timestamp kept the key, because time is not hashed. Changing the declared MODE value made a new key. Changing an undeclared file changed the real output but not the key, so the cache served old bytes.

What the real tool did on the shop repository

We repeated the same moves with turbo 2.11.10 on the shop repository. Every row below is from one scripted run, saved with its output.

You can see the key's ingredients yourself. Run turbo run build with --dry=json, a dry run that plans the tasks without running them. Read the inputs and hash fields of each task. In our run, each input file was listed with its git blob hash, the ID git itself gives a file's contents. It matched what git hash-object printed.

A declared environment variable appeared only as a SHA-256 hash of its value, so the value itself was not printed. This output format is undocumented as of 27 October 2026; pin your version before you script against it.

A wrong cache hit happens when something changed the output but was not part of the key. The tool restores an old result that looks perfectly valid. The usual causes are environment variables, outputs nobody listed, and inputs from outside the repository.

Environment variables that change the output

The shop's API build bakes in an API_URL environment variable. We built it for production, then for staging, with no turbo.json entry for that variable. Turborepo's default strict mode passes a task only the variables declared in turbo.json, plus a few such as PATH. So the build saw nothing and wrote undefined.

That run was also a cache hit, because nothing in the key had changed. Turborepo's docs warn about this: tasks that handle a missing variable quietly can produce unintended cache hits instead of failing.

Loose mode, set with --env-mode=loose, passes every variable but still hashes only the declared ones. Our production build ran first and was cached. The staging build then hit that entry and restored a bundle pointing at the production URL.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "env": ["API_URL"]
    }
  }
}

Bazel has the same rule in its own words. Only environment variables passed with --action_env become part of an action's definition, according to its remote caching docs. Anything else your compiler reads from the environment is invisible to the key.

Outputs you forgot to list

Turborepo caches only files named in outputs; its configuration reference says that omitting the key caches nothing. We removed the outputs line, built the API, deleted its dist folder and built again. Turborepo printed cache hit and replayed the logs, but dist was not restored.

This is the most confusing failure for beginners, because the log says success. The fix is to list every folder a task writes, then check by deleting it and running the build again.

Inputs from outside the repository

Bazel's docs list the known traps. Bazel does not track tools installed outside the workspace. An input file modified during a build might upload invalid results to the remote cache.

Bazel defines a hermetic build as one that returns the same output for the same source and configuration by isolating itself from the host machine. Its docs name common leaks: timestamps or build IDs written into outputs, system binaries that differ between machines, and writing to the source tree during a build.

If you are new to this topic, you can stop here. You now know what the graph, the fingerprint and the cache do, and why a cache can be wrong. The rest of the guide is for engineers running CI on a real monorepo.

A remote cache is a shared server holding the same hash-to-output entries as the local cache. Each machine asks it before running a task. A machine that misses builds the task and uploads the result. Every later machine with the same fingerprint downloads it.

Turborepo's Remote Cache API is plain HTTP, and its docs say any server that meets the published specification can act as one. To test it, we wrote a small Node server that keeps artifacts in memory. We pointed turbo at it with the TURBO_API, TURBO_TOKEN and TURBO_TEAM environment variables.

Then we cloned the shop repository twice, standing in for two fresh CI machines. Machine 1 missed all three tasks and uploaded three artifacts of about 250 bytes each. Machine 2 had no local .turbo folder at all, yet all three tasks were hits and dist came back.

GET /v8/artifacts/207936545a6dde6c   404  machine 1: not cached yet
PUT /v8/artifacts/207936545a6dde6c   202  machine 1: uploads after building
GET /v8/artifacts/207936545a6dde6c   200  machine 2: downloads, no build

Bazel and Nx work the same way with different protocols. Bazel takes --remote_cache with an HTTP or gRPC address, gRPC being a remote-call protocol, or --disk_cache for a local folder. Nx publishes an OpenAPI description, a machine-readable spec of an HTTP API, for self-hosted servers. It uses PUT and GET on /v1/cache/HASH.

Who should be allowed to write to the cache?

Only builds you trust. Bazel's remote caching docs advise taking care over who can write and suggest letting only your CI system write. The reason is the diagram above: whatever is stored under a hash is what everyone gets. Nx's self-hosted spec even refuses to overwrite an existing entry, so the first upload stays.

CVE-2025-36852, a public ID for a known security flaw published on 10 June 2025, describes this risk for remote caches kept in cloud storage buckets. Its record lists Nx's own cache plugins for S3, GCS and Azure storage and shared file systems, plus community plugins such as MinIO. Artifacts built in untrusted places, such as pull-request jobs, could poison the cache read by protected branches, the branches only reviewed code reaches. The record says checksums and access controls do not help, because the bad artifact is built before they apply.

1. 1

   Let trusted builds write

   Give write access only to CI jobs on protected branches, such as main. Developers' laptops and pull-request jobs read.

2. 2

   Make pull-request jobs read-only

   Bazel: --remote_upload_local_results=false. Turborepo: --cache=local:rw,remote:r, which printed Remote cache is read-only, skipping upload in our run. Nx self-hosted cache: give pull requests a read-only token. Its spec returns 403 when such a token tries to write.

3. 3

   Sign what you upload

   Turborepo can sign artifacts with HMAC-SHA256, a signature made with a shared secret, set in TURBO_REMOTE_CACHE_SIGNATURE_KEY. Artifacts that fail verification count as misses. Keep the key away from untrusted jobs, or signing proves nothing.

4. 4

   Keep untrusted results apart

   Use a separate cache or namespace for untrusted builds. The Remote Execution API has a salt field for exactly this: it places an action in a separate cache namespace.

5. 5

   Keep secrets out of logs

   Turborepo stores and replays terminal output as part of the artifact. Anything a task prints is shared with every machine that hits that entry.

Affected-target selection diffs your branch against a base, maps each changed file to the package that owns it, and adds every package that depends on those packages. Everything else is left out of the run. In the shop, an edit to utils selects utils and web, but never api.

# Turborepo 2.11.10: same as --filter=...[main...HEAD]
npx turbo run build --affected

# Nx 24.0.2: base defaults to main
npx nx affected -t build --base=main

# pnpm 12.15.0: changed packages plus their dependents
pnpm --filter "...[main]" run build

# Bazel, not run for this guide: reverse dependencies of utils
bazel query 'rdeps(//..., //packages/utils:utils)'

The three dots matter in Turborepo and pnpm. Three dots before a selector mean the package and its dependents. Inside the brackets, main...HEAD is a git range, a different meaning. In pnpm, three dots after it mean the package and its dependencies instead, so [main]... picked only utils.

Turborepo's run reference does not say whether uncommitted files count. In our runs they did. Nx's docs say its default head is your current file system, and pnpm's docs say uncommitted changes are included.

Why shallow CI clones break affected selection

Affected selection needs the history between the base and your commit. A shallow clone, a checkout that fetches only the latest commits, does not have it. We cloned the shop's feature branch with depth 1 and ran turbo run build --affected.

Turborepo warned that it was unable to detect the git range and assumed all files had changed. All three packages were selected. A full clone with TURBO_SCM_BASE set to origin/main selected only utils and web again.

Nx's docs give the same warning for GitHub: without full git history there is no base commit to compare against. They suggest fetching full history and setting the base and head commits explicitly.

Which base should a pull request compare against?

Turborepo compares main...HEAD by default; the three dots mean git compares from the point where your branch left main. In our run, a later api commit on main was not selected for a branch that changed only utils. TURBO_SCM_BASE and TURBO_SCM_HEAD override the range. pnpm, since version 12.7.0, compares against the merge base too.

Nx recommends setting the base to the last commit on main whose CI run succeeded. That way a failure on main is retried by the next change instead of being skipped. Nx's docs also say a lock file change affects every task by default.

Affected selection and caching work together. Selection trims the list of tasks before anything runs; the cache skips unchanged tasks that are still on the list. Nx's docs warn that an undeclared input or output can make it miss a task, so a regular full build on main is a sensible safety net.

Make the cache correct, share it, shrink the task list, then spread what is left across machines. Ten minutes is a target, not a promise; measure each step on your own repository. The order matters, because a fast but wrong cache ships bad builds.

1. 1

   Measure where the time goes

   Turborepo's --summarize writes a JSON file in .turbo/runs with each task's timing, hash and cache status. Nx 24.0.2 prints the run duration, cache hit rate and critical path after each run.

2. 2

   Make cache hits trustworthy

   Declare environment variables and outputs. Run the same build twice and expect every task to hit. Use a dry run to read the inputs of any task that misses unexpectedly.

3. 3

   Share results through a remote cache

   Let main-branch CI write and everything else read. A pull request then reuses whatever main already built for unchanged packages.

4. 4

   Run only affected tasks on pull requests

   Fetch enough git history, set the base explicitly, and use --affected or nx affected. Check the log for a warning that all files changed.

5. 5

   Cache the folder the tool really uses

   If your CI saves a local cache between runs, point it at the current default folder. Nx 24 moved it, as the callout below explains.

6. 6

   Spread the remaining work

   Bazel's remote execution sends actions to a pool of workers over the same open protocol as its cache. Split slow test suites so the critical path shrinks.

7. 7

   Keep a full build as a safety net

   Run every task on main on a schedule. It catches anything the graph or the affected logic missed.

Bazel also caches test results. Its user manual says that, by default, a test reruns only in four cases. The test or its dependencies changed, it failed, it is marked external, or you asked for repeated runs.

Pick by how fine-grained and how strict your builds need to be. In our runs, Turborepo and Nx cached whole package tasks in a JavaScript workspace, configured from files it already had. Bazel caches individual actions, supports many languages, and asks you to declare every target in BUILD files.

Turborepo was the smallest step for our existing npm workspace: one turbo.json file. Any tracked file change inside a package reruns that package's task, which is coarse but easy to reason about.

Nx works at the same project level and adds tooling around the graph, such as nx graph and affected selection with a configurable base. Its cache location and lock file rules differ from Turborepo's, as shown above.

Bazel's action-level key means one changed source file reruns the actions that read it, plus later actions whose inputs then change. Its remote cache and remote execution use the open Remote Execution API. Other build tools speak it too, including Buck2, Pants and Please, and servers such as Buildbarn, Buildfarm and BuildGrid implement it.

In our judgement, a team should move to action-level builds only when package-level caching has been made correct and is still too slow. That is an opinion, not a measurement; test it on your own repository first.

Frame it as a correctness problem first and a speed problem second. Interviewers want to hear what goes into the cache key and what happens when it is wrong.

1. 1

   State the problem

   Many packages share one repository. Every change rebuilds and retests everything, so CI time grows with the repository, not with the change.

2. 2

   Draw the build graph

   Packages are boxes, imports are arrows. Tasks run in dependency order, and independent ones run in parallel. The longest chain sets the minimum time.

3. 3

   Define the cache key

   Hash the command, input file contents, declared environment variables and dependency hashes. Store outputs by content hash, and map each key to its outputs.

4. 4

   Share the cache safely

   Add a remote cache. Only trusted main-branch builds write; pull requests read. Sign artifacts and keep untrusted results in a separate namespace.

5. 5

   Shrink the work

   Diff against a base commit, map files to packages, add their dependents. Fetch enough history, and run a full build on main as a safety net.

6. 6

   Name the failure modes

   Undeclared inputs give stale hits, unlisted outputs give empty hits, shallow clones select everything, and open write access allows cache poisoning.