Monorepo

A single version-controlled repository holding many projects/services together, versus polyrepo (one repo per project). A structural decision in the version-control + build corner of developer-tooling — it changes how dependencies are shared, how builds scope, and what the VCS must handle.

What it solves: dependency drift

The case for a monorepo is coordination. In polyrepo, shared libraries are published as independently-versioned artifacts, so services drift onto different versions — "diamond dependency" runtime surprises, duplicated upgrades, and multi-repo coordinated deploys. A monorepo resolves shared dependencies from source at a single revision and lets a change span many projects in one atomic commit. Block consolidated ~450 JVM repos for exactly this reason.

What it costs: builds, VCS, and a platform team

The case against is that scale moves the cost elsewhere:

• Build/CI scaling — you can't rebuild everything on every commit, so you need dependency-graph analysis + selective/incremental builds and merge queues (Block ran 8,800 builds/week at p90 CI ~10 min via exactly these).
• VCS performance — a giant repo strains Git, pushing teams toward sparse checkouts and, at the extreme, purpose-built VCS for huge trees (lore's content-addressed/on-demand-hydration design is the engine-side answer to the same scaling pressure).
• A funded platform team — the load-bearing caveat from block-monorepo-migration: "if you can't commit to properly funding a platform team… you'll probably do better with a polyrepo." Monorepo trades per-team coordination overhead for centralized platform investment.

Build-tool options

Build systems built for monorepos (Bazel, Buck, Pants, Nx, Turborepo) provide the selective-build graph; notably Block built custom Gradle/IntelliJ tooling instead of adopting Bazel, a reminder that the concept is separable from any one tool.

A monorepo also assumes a CI system able to act on that graph, which is the part this spoke held only obliquely until harness-open-source arrived — a self-hostable platform that puts source control, pipelines, dev environments and an artifact registry in one binary. Its bet is the mirror image of the one above: where a monorepo consolidates the code and then needs tooling to selectively un-consolidate the build, Harness consolidates the tools around whatever layout the code already has.

And the layer underneath both (2026-09-04)

Neither the build graph nor the CI system decides what a package can import; the package-manager does. In a monorepo that stops being a detail — pnpm's refusal to hoist transitive dependencies means an undeclared import fails at install time rather than at some later point when the package that happened to provide it is removed. A workspace is where a flat node_modules does its most damage, because every package shares one.

Related

block-monorepo-migration · harness-open-source · lore · package-manager · pnpm · developer-tooling · synthesis