Most organizations don't have a single giant monorepo. They have a handful of monorepos per team or domain, plus dozens of standalone repos. Consolidating everything into one repository is not just a technical challenge. The organizational side (bringing teams along, changing workflows, ensuring adoption) is often harder than the code migration itself.
Synthetic monorepos let you get monorepo benefits without that consolidation.
What is a synthetic monorepo?
Section titled “What is a synthetic monorepo?”A synthetic monorepo connects separate repositories into a unified dependency graph without moving any code. Which repo depends on which, what a change affects downstream, how projects relate across teams: all of that becomes visible automatically.
Unlike a traditional monorepo where all code lives in one repository, a synthetic monorepo leaves each repository where it is. Instead, it builds a cross-repo graph that tooling can reason about, just as if the code were in one place.
What synthetic monorepos enable
Section titled “What synthetic monorepos enable”A synthetic monorepo addresses several downsides of a polyrepo setup:
Visibility — An automatic cross-repo dependency graph shows which repo depends on which and what a change affects downstream. Always up to date, discovered from actual code — not a manually maintained spreadsheet or catalog. Nx implements this through the Workspace Graph.
Coordination — Cross-repo changes no longer require manually sequencing PRs, managing compatibility, and coordinating release order. Tooling on top of the graph enables impact analysis, coordinated changes, and conformance checking across repo boundaries.
Governance — Organizational standards apply across every connected repo through conformance rules. Scheduled custom workflows check repos continuously — even ones nobody has touched in months. Detection and enforcement happen automatically, not through tickets and follow-ups.
CI intelligence — Affected detection, remote caching, and distributed task execution work across the full graph, not just within a single repo.
AI agents — AI coding agents are dramatically less effective in polyrepos — they can only see one repo at a time, so cross-repo features require you to manually shuttle context between sessions. A synthetic monorepo gives agents cross-repo visibility, enabling coordinated changes, parallel execution, and automatic PR creation across boundaries. Self-healing CI catches failures automatically.
When to use a synthetic monorepo vs. a real monorepo
Section titled “When to use a synthetic monorepo vs. a real monorepo”A real monorepo is the best option when you can consolidate. It gives you atomic commits, a single toolchain, and the simplest mental model.
A synthetic monorepo is the better starting point when:
- Consolidation isn't feasible yet: team autonomy concerns, divergent CI setups, or hundreds of repos make migration impractical.
- You need cross-repo visibility now: you can't wait months for a migration to see how projects relate across teams.
- Teams need to stay autonomous: each team keeps their repo, workflow, and release cadence while still participating in a unified graph.
The two aren't mutually exclusive. Start synthetic for org-wide visibility, then consolidate tightly coupled teams into real monorepos where it makes sense.
Synthetic monorepos with Nx Polygraph
Section titled “Synthetic monorepos with Nx Polygraph”Nx implements synthetic monorepos through Nx Polygraph. Polygraph connects existing repositories into a unified, intelligent graph that powers the visibility, coordination, and CI features described above. It works with any repo, even those that don't use Nx, and requires zero changes to target repos.
Learn more about getting started with Nx Polygraph.