Lesson 0001 · ~10 minutes

When monorepos fit (and when they don’t)

One skill: place “one repo, many projects” on the repo strategy spectrum and pick a monorepo only when the hard problem is multi-project consistency + coordinated change — not “one giant app,” and not “git folders without tooling.”

Lesson 2 → Glossary Resources Mission

Win for this lesson

After the quiz, you can defend “monorepo yes / no” for a set of related projects — and reject both “monolith in disguise” and “polyrepo with copy-pasted configs forever” without installing moon yet.

1. What a monorepo is

A monorepo is a single repository containing multiple distinct projects, with well-defined relationships between them. Nx’s definition is the cleanest public framing for this track: apps, libraries, and tools can share a stack or not; each project can still build, test, and deploy on its own.

Three confusions to kill early:

Not a monolith. Monolith = one deployable application. Monorepo = version-control strategy. Teams often use a monorepo while splitting a monolith into many projects.
Not “many folders in git” alone. That is code collocation. Without a project graph, task orchestration, and usually affected runs, CI and local workflows get slower and messier as the tree grows (Nx: why collocation isn’t enough).
Not only Google-scale. Google’s CACM paper proves the model can scale with heavy tooling. The same benefits (shared code, atomic API changes, one set of conventions) show up with five related packages — if you invest in tooling proportional to pain.

2. Problems monorepos are good at

Your mission is multi-project maintenance. Monorepos earn their keep when several of these hurt in a polyrepo world:

Duplicated scripts and configs — every repo reinvents lint/test/build; “how do I run this?” changes per folder.
Version drift — same library or Node major everywhere, except the one app that never upgraded.
Cross-project changes — rename a shared type or API and you need a chain of PRs across repos, with a broken window in between. A monorepo enables atomic changes (Google paper + Nx: same idea at different scales).
CI fragmentation — N pipelines, N secret layouts, N “green but incompatible” combinations.
Sharing without publish theater — a shared package can be a folder + graph edge, not a private npm release for every tweak.

Google’s paper lists the classic advantages in larger form: unified versioning, code sharing, simplified dependencies, atomic changes, large-scale refactor, collaboration, flexible ownership, visibility.

3. Costs you must budget for

Monorepos are not free. Expect to pay in:

Tooling — graph-aware tasks, caching, affected CI. Without it, one repo can be worse than many (run everything on every push).
Code health / coupling — easy deps invite spaghetti; Google explicitly calls out unnecessary dependencies and the need for boundaries and cleanup.
Ownership — CODEOWNERS / review paths must replace “repo = team boundary.”
Migration cost — history, CI, permissions, and habits from polyrepos don’t vanish on day one.

Rule of thumb

Choose monorepo when related projects benefit from one truth + coordinated change, and you will fund the tooling. Choose polyrepo when isolation, separate access, or truly independent release/ownership dominate — and accept coordination cost.

4. Spectrum (this track’s map)

Polyrepo

One repo per project. Max isolation. Shared standards and cross-cutting changes are process + automation debt.

Collocated

Many projects in one git tree, little monorepo tooling. Fine as a bridge; dangerous as an end state at scale.

Monorepo + tools

One repo, project graph, shared tasks, toolchain, affected/cache. Your target shape for multi-project standardization.

Monolith

One deployable app (architecture). Can live in poly- or monorepo — different axis. Don’t confuse with monorepo.

Package manager workspaces (pnpm/npm/Yarn) sit in the middle: they link local packages. They are not a full monorepo build system. Tools like moon add the orchestration layer (tasks, graph, toolchain, cache) — that is later lessons.

5. Practice — defend yes / no

Equal-length choices. Pick, then read the feedback. No moon install yet.

Question 1

“We’ll put the whole product in one monorepo, so it becomes one monolith we ship together.” What’s wrong?

Question 2

Which situation is the strongest monorepo fit?

Question 3

You merge five repos into one git root and keep each package’s own ad-hoc scripts. CI runs all tests on every PR. Best diagnosis?

Question 4

When is polyrepo usually the better default?

6. Primary source (read when you can)

Recommended primary: Nx — What is a Monorepo? (~10–15 min). Tight definitions: monorepo vs monolith, benefits, why collocation fails, tool layers.

Depth primary (skim the advantages/costs): Potvin & Levenberg — Why Google Stores Billions of Lines of Code in a Single Repository (CACM). Use it to pressure-test “why” and “what it costs,” not to copy Piper.

moon docs wait until we wire a workspace — but bookmark moon: Workspace for the next step.

Ask your teacher Anything fuzzy — poly vs mono for a real repo of yours, collocation vs “done,” how moon maps onto this spectrum — ask in chat. Follow-ups are part of the course.