Monorepos

The problem: one button, five repositories

Picture a travel company with three web apps: the public booking site, the customer account area, and an internal admin tool. All three use the same Button, the same date picker, and the same API client. Each app lives in its own Git repository, and the shared code lives in two more: ui-kit and api-client. Five repositories in total.

A designer asks for a small change: the primary button needs a loading state. The engineer opens a pull request in ui-kit, gets it reviewed, merges it, and publishes version 4.3.0 to the private npm registry. That is step one of many.

Now each app has to take the new version. Three more pull requests, three more reviews, three more CI runs. The admin tool is still on ui-kit version 3 because nobody had time to handle a breaking change from last spring, so it cannot take 4.3.0 at all. Two weeks later the booking site has the loading button, the account area has it on a branch, and the admin tool never gets it.

What goes wrong with many repositories

Keeping each project in its own repository is called a polyrepo setup. It is a fine choice for many teams, but when several apps share a lot of code, it creates four kinds of friction.

• Slow cross-cutting changes. A change to shared code takes one pull request per repository, in order: publish first, then upgrade each user.
• Version drift. Each app pins its own version of the shared code. Over time the apps spread across ui-kit 3, 4, and 5, and bugs fixed in 5 stay in 3.
• Hidden breakage. The author of a shared package cannot easily run the apps' tests before publishing, so a break shows up weeks later, when an app upgrades.
• Copied setup. Every repository has its own TypeScript config, ESLint rules, and CI pipeline. They start as copies and drift apart; a CI fix is made five times.

What a monorepo is (and is not)

A monorepo is one version-control repository that holds many projects: several apps, the shared packages they use, internal tools, and shared configuration. In the travel company's case, all five repositories become folders in one repository: apps/booking, apps/account, apps/admin, packages/ui, and packages/api-client.

Now the loading button is one pull request. It changes packages/ui and the apps that need the new prop, and CI runs the tests of every app that uses the button. If the admin tool breaks, the pull request is red before anything merges.

A monorepo is not a monolith, which is one app built and deployed as a single unit. The three apps still have separate builds and deploys. What they share is the repository, the tooling, and the ability to change many of them in one commit.

The new problems a monorepo brings

Without tools, a monorepo gets slow and messy as it grows. Most of this lesson is about those tools.

• Linking. How does apps/booking import packages/ui without publishing it? Answer: workspaces.
• Speed. If every pull request builds and tests everything, CI time grows with the whole repository. Answer: a task runner that runs only affected work and caches results.
• Ownership. With 40 teams in one repository, who must review a change to packages/ui? Answer: a CODEOWNERS file and boundary rules.
• Versions. Do internal packages have version numbers at all? Answer: a clear policy, often none for internal code and changesets for anything published.

The mental model: one repository, one graph

The one picture to keep in your head is a dependency graph. Every app and package is a node. An arrow from booking to ui means "booking depends on ui". Monorepo tools read this graph from the package.json files, and almost every feature they offer is a question asked of it.

Think of a city's water pipes. After repairing one main pipe, you check only the houses downstream of it. And a street whose pipes have not changed since last week keeps last week's inspection report.

Reading the graph in two directions

The graph is useful in both directions. Take the travel company's repository in the figure above.

• Dependencies (follow the arrows forward). booking depends on ui and api-client, and through them on tokens and utils. To build booking, those must be built first. This direction answers "what must run before me?"
• Dependents (follow the arrows backward). utils is used by ui and api-client, and through them by every app. This direction answers "what could my change break?" A package with many dependents is risky to change and expensive to test.

Every arrow should point from something more specific to something more general: apps depend on features, features depend on shared UI, shared UI depends on tokens and utilities. The graph must have no cycles. If ui imports from api-client and api-client imports from ui, neither can be built first, and tools will refuse to run or report an error.

From the package graph to the task graph

Packages do not run; tasks do. A task is one script in one package, such as ui#build or booking#test. The tool combines the package graph with rules you write, like "before building a package, build its dependencies", to produce a task graph: which tasks must finish before which.

The task graph gives you three features at once:

1. Correct order. tokens#build runs before ui#build, which runs before booking#build. Nobody has to write that order by hand in a CI script.
2. Parallelism. Tasks with no path between them run at the same time. utils#build and tokens#build do not depend on each other, so they share the CPU cores. Lint tasks usually have no dependencies at all, so all of them can start at once.
3. Skipping. If a change touched only api-client, then ui and tokens cannot be affected by it. Their tasks can be skipped entirely (an affected run) or answered from a cache (a cache hit).

The shape of the graph decides your CI cost

A wide, shallow graph with small packages is cheap: most changes touch one leaf and affect one or two apps. A graph where one giant common package sits under everything is expensive: almost every pull request changes common, so almost every pull request affects everything. Tools cannot save you from that shape. Splitting the giant package is the fix.

Workspaces: linking packages without publishing

The foundation of every JavaScript monorepo is the package manager's workspaces feature. npm (since version 7), Yarn, pnpm, and Bun all have one. You tell the package manager which folders hold packages, and a single install at the root sets up all of them together.

The key trick is linking. When apps/booking lists @travel/ui as a dependency, the package manager notices that a package with that name lives in packages/ui. Instead of downloading it from a registry, it creates a symbolic link (a pointer to another folder) in booking's node_modules. An edit to packages/ui/src/Button.tsx is visible to booking at once, with no publish and no reinstall.

# pnpm-workspace.yaml (at the repository root)
packages:
  - "apps/*"
  - "packages/*"

# apps/booking/package.json (the relevant part)
# "dependencies": {
#   "@travel/ui": "workspace:*",
#   "@travel/api-client": "workspace:*",
#   "react": "^19.1.0"
# }

The workspace protocol

The version workspace:* is the workspace protocol, supported by pnpm, Yarn (version 2 and later), and Bun. It means "always use the local copy, never the registry". If the local package is missing, the install fails loudly instead of quietly downloading some old published version with the same name. npm does not support this protocol; with npm you write a normal range such as * and npm links the local package when its version matches.

When you publish a package that uses it, pnpm and Yarn replace workspace:* with the real version number, so it is safe for published packages too.

One install, one lockfile

A workspace has a single lockfile at the root (pnpm-lock.yaml, package-lock.json, yarn.lock, or bun.lock). It records the exact version of every third-party package for every project. A new engineer runs one install and every app works, and an upgrade such as React 18 to 19 is one diff that CI checks against every app.

How pnpm stores packages, and why it is strict

pnpm is a common choice for monorepos because of how it lays out files. Classic npm and Yarn 1 copy packages into each node_modules folder and hoist them: they move dependencies up to the root node_modules so they can be shared. pnpm does something different, in three layers.

1. A content-addressed store. Every file of every package version is saved once, in a global store on the machine, under a name derived from a hash of its content. Ten projects using react@19.1.0 share one copy on disk. If two versions of a package share most files, the identical files are stored once.
2. A virtual store per repository. node_modules/.pnpm contains one folder per package version, filled with hard links (a second name for the same file on disk) into the global store. Each of these folders also gets symbolic links to exactly the dependencies that package declares.
3. Thin top-level folders. Each project's own node_modules contains only symbolic links to the packages it lists in its package.json. Nothing else.

That last layer is the strictness. With hoisting, booking can import dayjs even though only ui declared dayjs, because hoisting put dayjs at the root where Node.js finds it. That is a phantom dependency: code that works by accident.

A phantom dependency breaks the day ui drops dayjs, or when booking is built or deployed on its own. Under pnpm, booking cannot see dayjs unless it declares it, so the mistake fails on the developer's machine, not in production.

Since version 9.5, pnpm also offers catalogs: you name a third-party version once in pnpm-workspace.yaml (for example react: ^19.1.0) and each package writes "react": "catalog:". Upgrading React for every app becomes a one-line change. Since version 10, pnpm also skips dependencies' install scripts unless you list them as allowed, which blocks a common supply-chain attack.

Task runners: Turborepo, Nx, and affected runs

Workspaces link packages, but they know little about running tasks. pnpm -r run build runs build in every package, in dependency order, every time. That is fine with 5 packages and painful with 60. A task runner sits on top of the workspace, builds the task graph, and decides what actually needs to run.

Declaring how tasks relate

You describe each kind of task once, for the whole repository. Here is a Turborepo config. Nx expresses the same ideas in nx.json under targetDefaults, using the same ^build notation.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**"],
      "env": ["API_URL"]
    },
    "test": { "dependsOn": ["^build"], "outputs": ["coverage/**"] },
    "lint": {},
    "dev": { "cache": false, "persistent": true }
  }
}

• dependsOn: which tasks must finish first. ^build gives you the topological order: dependencies before dependents.
• inputs: which files can change the result. By default, all files tracked by Git in the package.
• outputs: which files the task produces, so the cache can save and restore them. Forget it and a hit restores logs but no files: "cache hit, but dist is empty".
• env: which environment variables can change the result (next chapter).
• cache: false and persistent: for dev servers and watchers, which never finish and must never be replayed from a cache.

Affected runs: only what a change can reach

The first big saving is to not even consider tasks that a change cannot reach. The tool asks Git which files changed compared with a base (usually main), maps each file to the package that contains it, then walks the graph backward to find every dependent. Only those projects are affected.

# Nx: test every project affected by the changes on this branch
nx affected -t test --base=origin/main

# Turborepo: the same idea
turbo run test --affected

# Turborepo filter syntax: ui plus everything that depends on it
turbo run build --filter=...@travel/ui

# Turborepo: packages changed since main, plus their dependents
turbo run test --filter=...[origin/main]

Try it on the lab below, which assumes inputs narrowed to source files as in the config above. Pick the package you changed and what changed in it, then switch between running everything, running only affected projects, and running everything with a warm cache. Watch which tasks run, which are skipped, and which are replayed from the cache.

Notice what the lab shows: affected runs and caching overlap but are not the same. Affected detection works at the level of whole projects and needs a base commit. Caching works at the level of single tasks and needs no base at all; it only asks "have I seen these exact inputs before?" Mature setups use both.

Choosing a task runner

Task caching: never do the same work twice

Affected runs skip projects a change cannot reach. Caching goes further: it skips any task whose inputs are exactly the same as some earlier run, on any machine. It is the single biggest reason large monorepos stay fast.

How a task gets its fingerprint

Before running a task, the tool computes a hash: a short fingerprint, such as 8f3a91c2, that changes whenever anything that could change the result changes. The exact recipe differs by tool, but it is built from the same parts:

• the contents of the task's input files (by default, every file in the package that Git tracks)
• the hashes of the same task in the packages it depends on, so a change to utils changes the hash of ui#build too
• the task's own configuration, and the script it runs from package.json
• the resolved versions of its third-party dependencies, from the lockfile
• the values of environment variables you declared as inputs
• global inputs that affect everything, such as the root config files

The tool then looks the hash up. If it finds a saved result, it restores the output files (dist/, coverage/) and prints the saved logs, so the run looks the same as before. That is a cache hit, and it typically takes well under a second. If not, the task runs and its outputs and logs are saved under that hash for next time.

Local cache and remote cache

The local cache is a folder on your machine. It helps when you switch branches and back, but does nothing for CI, because each CI machine usually starts empty.

A remote cache is shared storage that every developer and every CI job reads from and writes to. Vercel offers one for Turborepo and Nx Cloud offers one for Nx; both tools can also use a self-hosted server. With a remote cache, a build a teammate ran an hour ago is a hit for you, and a CI job on main warms the cache for every branch that starts from it.

The dangerous case: a wrong hit

A cache miss only costs time. A wrong hit costs correctness: the tool replays an old output when the real result would have been different. It happens when a task reads something that is not part of its hash. The most common culprit is an environment variable.

Say booking#build bakes API_URL into the bundle, but nobody declared API_URL as an input. This can happen in Nx, or in Turborepo's older loose mode. CI builds for staging with API_URL=https://staging.api, and an hour later the production pipeline builds the same commit with API_URL=https://api.

The hash is identical, so the cache replays the staging bundle, and production users talk to the staging API. Use the lab below to see which edits change the hash and which do not.

• Declare every environment variable a task reads. Turborepo uses env per task and globalEnv for all tasks; since version 2.0 its default strict mode hides undeclared variables from tasks, so a build cannot quietly depend on one. Nx lets you add { "env": "API_URL" } to a task's inputs.
• Keep tasks deterministic. No timestamps, random ids, or machine paths in outputs.
• Declare outputs fully. If a task writes dist/ and types/, list both, or a hit restores only half.
• Do not cache tasks with side effects. Deploys, database migrations, and publishing should run every time.

The opposite mistake, inputs that are too broad, is safe but slow: a README.md edit should not rebuild anything. Narrow inputs so docs and test files do not invalidate builds; in Nx, a named input like production that excludes *.spec.ts files is the common pattern.

Shared packages: UI, config, and source versus built

Most frontend monorepos end up with the same handful of shared packages. Each one is a normal package with a package.json and a name, so imports read like any library: import { Button } from "@travel/ui".

Config packages

Instead of 12 copies of tsconfig.json drifting apart, each package extends one shared base. Turning on a stricter compiler option becomes one change that CI checks everywhere.

// packages/tsconfig/base.json
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "noUncheckedIndexedAccess": true,
    "skipLibCheck": true
  }
}

// apps/booking/tsconfig.json
{
  "extends": "@travel/tsconfig/base.json",
  "include": ["src"]
}

ESLint works the same way: an eslint-config package exports a flat config array, and each package's eslint.config.js imports and spreads it, adding local rules if needed.

A small public surface with exports

Every shared package should say exactly what callers may import, using the exports field of its package.json. Anything not listed there cannot be imported by name. Without it, apps reach into deep paths like @travel/ui/src/button/internal/useRipple, and every refactor inside ui breaks someone. The component API lesson covers how to design the surface itself.

Consume as source, or build first?

The biggest design choice for an internal package is whether apps consume its source (the TypeScript files) or a built copy (compiled JavaScript in dist/). Both are common; they trade speed of editing against speed and isolation of builds.

Code ownership, boundaries, and dependency hygiene

In a polyrepo, the repository itself is a wall: the checkout team cannot change the search team's code without asking for access. In a monorepo anyone can open a pull request that touches anything. That is the point, but it needs three kinds of rules: who reviews what, who may import what, and which third-party versions are allowed.

CODEOWNERS: who must review a change

A CODEOWNERS file maps path patterns to people or teams. GitHub and GitLab both read it. When a pull request touches a matching path, the owners are added as reviewers automatically, and with branch protection turned on (on GitHub, "Require review from Code Owners"), the pull request cannot merge until an owner approves.

• The last matching pattern wins on GitHub. Put the broad catch-all first and the specific folders after it, or the catch-all will override them.
• Own the shared files too. The root package.json, the lockfile, turbo.json or nx.json, and the CI config affect everyone. Give them to a platform team so one team cannot quietly change the build for all.
• Owners should be teams, not people. People go on holiday; a team handle keeps working.
• A big change gets many owners. A rename across 30 apps may need 30 approvals, so allow a small group to approve mechanical codemods, or split the change per owner.

Boundaries: who may import what

Ownership controls who reviews a change, not what gets imported. Left alone, apps import each other's components, a UI package imports the API client, and the graph turns into a web where every change affects everything.

Boundary rules fail the lint step when an import crosses a line you drew. Nx tags each project, for example scope:booking and type:ui, and its @nx/enforce-module-boundaries ESLint rule allows only the arrows you list, such as "type:app may depend on type:ui and type:data; type:ui may depend only on type:ui and type:util". Outside Nx, eslint-plugin-boundaries or a dependency checker like dependency-cruiser does a similar job. The same rule should also stop one app from importing another app at all.

Dependency hygiene: one version policy

The same drift that hits internal packages in a polyrepo can hit third-party packages in a monorepo. If booking uses React 19.1 and admin uses React 18.3, then ui must work with both, two copies of React may end up in the lockfile, and a shared component can break with the confusing "invalid hook call" error when it meets the wrong copy.

Many teams adopt a one version policy: each third-party package appears in the repository at exactly one version. Google's monorepo is known for a strict rule like this. In JavaScript you can enforce it in a few ways:

• pnpm catalogs: declare react: ^19.1.0 once in pnpm-workspace.yaml; every package writes "react": "catalog:".
• syncpack: a command-line tool that scans every package.json, reports mismatched versions, and can fix them. Run its check in CI so mismatches fail the build.
• Root-level overrides: pnpm.overrides, npm overrides, or Yarn resolutions force one version of a transitive dependency, useful for a security fix deep in the tree.
• Peer dependencies for shared packages: ui lists react as a peer dependency, not a normal one, so it always uses the app's single copy.

The cost: upgrading React means upgrading every app at once. Teams handle it with codemods, a short exception list for stragglers, and grouped upgrade pull requests from Renovate or Dependabot that CI tests against every app.

Versioning internal packages

In a polyrepo, every shared package needs a version number, because that is the only way an app can say which code it wants. In a monorepo you get to choose. The choice shapes how changes flow, so make it on purpose.

Option 1: no versions at all (live at head)

Most monorepos keep internal packages "private": true and depend on them with workspace:*. Every app always uses the code at the current commit. There is no ui version 4 or 5; there is only ui on main. This is often called living at head.

The rule that makes it work: whoever changes a shared package fixes every caller in the same pull request. CI runs every affected app's tests, so a break is caught before merge, and nobody is ever left on an old version. This is the biggest practical benefit of a monorepo.

The cost shows up with breaking changes to widely used packages. Renaming a prop used in 400 places across 30 apps is a big pull request with many owners. Two techniques keep it manageable:

1. Expand, then contract. Add the new API next to the old one. Move callers over in small pull requests, team by team. Delete the old API when nobody uses it.
2. Codemods. A script (for example with jscodeshift or ts-morph) rewrites every caller mechanically, so the big pull request is generated, not hand-written.

Option 2: real versions, fixed or independent

Packages that leave the repository need real semver versions: an SDK for partners, an open-source component library, or a package another repository installs. There are two styles.

Changesets: recording intent with each change

Changesets is the most common release tool for JavaScript monorepos. Its idea is simple: the person who makes a change knows best whether it is a patch, a minor, or a major change, so they record that in the same pull request, as a small Markdown file.

---
"@travel/ui": minor
"@travel/tokens": patch
---

Button: add a `loading` prop that shows a spinner and sets aria-busy.

At release time, changeset version reads all pending files, picks the highest bump for each package, and updates versions and CHANGELOG.md files. It also bumps packages that depend on a changed package when their dependency range needs updating. changeset publish then publishes what changed.

The official GitHub Action automates this with a standing "Version Packages" pull request: merging it releases. Config options fixed and linked give you fixed or grouped versioning for chosen packages. The design systems lesson walks through this flow for a component library.

CI at scale and what breaks

A monorepo's health shows up in one number: how long a typical pull request waits for CI. Here is how the earlier tools combine for the travel company at 12 apps and 40 packages. The numbers are illustrative; the shape is typical.

• Run everything, no cache: about 38 minutes. Every task for every project, on every pull request.
• Affected only: about 11 minutes. A typical change touches one package and its dependents. Changes to widely used packages still run most of the graph.
• Affected plus a warm remote cache: about 4 minutes. Affected tasks whose inputs match an earlier run, often on main or a previous push, are replayed.
• Plus spreading tasks across machines: about 2 minutes. Nx and some CI systems split the remaining tasks across several machines, which helps when they are many and independent.

Watch the cache hit rate

The cache hit rate is the share of tasks answered from the cache. Track it per task type over time, from the tool's run summaries (turbo run --summarize, or the Nx Cloud dashboard). A healthy repo usually sees most lint and test tasks hit on a typical pull request. A sudden drop means something entered every hash, for example:

• a root file listed as a global input that changes in every commit, such as a generated version file
• an environment variable that differs on every CI run, such as the build number or commit time, declared as a task input
• a lockfile that churns because bots update dependencies daily
• a non-deterministic build writing a timestamp into output that a later task hashes

To find the culprit, diff the hashed inputs of two runs of the same task: Turborepo's --dry=json output and Nx Cloud's run details both list them.

Failure modes and how you notice them

Git at scale

Git itself slows down in very large repositories, though most frontend monorepos never get there. Partial clone (git clone --filter=blob:none) downloads file contents only when needed. Sparse checkout (git sparse-checkout set apps/booking packages) puts only some folders on disk. Microsoft's scalar tool bundles these settings.

Choosing a monorepo, moving in, and the interview

A monorepo is not automatically better. It trades independence for consistency, and it asks for investment in tooling. The question is whether your projects share enough code, and change it often enough, for that trade to pay off.

Large monorepos in the wild

The famous examples are huge. Google described its single repository in a 2016 paper by Rachel Potvin and Josh Levenberg: billions of lines of code, tens of thousands of engineers, a custom version control system called Piper, and a build system called Blaze, whose open-source version is Bazel.

Meta keeps most of its code in a few very large repositories and open-sourced its Git-compatible client, Sapling, in 2022. Microsoft moved the Windows codebase to Git and built a virtual file system and the scalar tool to make it workable. These numbers are mostly self-reported and change over time, so treat them as orders of magnitude.

The lesson is not "put everything in one repo" but that these companies built serious tooling to make it work. Open-source projects such as Babel, React, Next.js, and Vite use smaller workspace monorepos, closer to what most frontend teams need.

Migrating into a monorepo

Move in steps, keep every app deployable throughout, and start with the most connected projects: the shared packages and their heaviest users.

1. Set up the shell. An empty repository with workspaces, the task runner, shared tsconfig and ESLint packages, CI with affected runs, and a CODEOWNERS file.
2. Import with history. Rewrite each old repository so its files live under the target folder (for example with git filter-repo --to-subdirectory-filter packages/ui), then merge it in. git log and git blame keep working.
3. Switch links. Change each app's dependency on the published @travel/ui to workspace:*. Fix the breakages that show up: these are the version drift you already had, now visible.
4. Align third-party versions. Run syncpack or set pnpm catalogs, and upgrade the stragglers. Expect this to be the slowest step.
5. Move deploys. Point each app's deploy pipeline at its folder, with a filter so a deploy runs only when that app is affected.
6. Archive the old repositories as read-only, with a README pointing to the new location.

Using it in a system design interview

Monorepos come up when the design has several apps or teams sharing code: a design system, a micro-frontend platform, web plus mobile web, or a customer app plus an admin tool. Bring it up when you discuss how the codebase is organized, not as the first thing.

• Draw the package graph: apps on top, shared packages below, arrows down. Mark which packages are published and which are internal.
• Say how changes flow: internal packages live at head with workspace:*; published packages use changesets.
• Say how CI stays fast: affected runs, a remote cache with declared inputs, and a graph kept shallow by boundary rules.
• Name a trade-off: shared upgrades and shared CI reduce team independence; micro-frontends with separate repos are the other end of that scale.

By level: a junior answer explains workspaces and why one pull request beats five. A senior answer adds caching, affected runs, ownership, and versioning. A staff answer adds graph shape, cache safety, CI metrics, and migration.