- Made with love by Nx
Monorepos are gaining renewed importance as AI agents reshape how developers work. Repository boundaries create friction that agents amplify: context loss across repos, duplicated setup, manual coordination of cross-cutting changes. Understanding monorepos (and how to set them up right) is becoming a core skill.
We created this resource to help developers understand what monorepos are, what benefits they bring, and what to look for in monorepo tooling.
Let's define what we and others typically mean when we talk about Monorepos.
We at Nx think this is the most consistent and accurate statement of what a monorepo is among all the established monorepo tools.
Consider a repository with several projects in it. We definitely have “code colocation”, but if there are no well defined relationships among them, we would not call it a monorepo.
Likewise, if a repository contains a massive application without division and encapsulation of discrete parts, it's just a big repo. You can give it a fancy name like "garganturepo," but we're sorry to say, it's not a monorepo.
In fact, such a repo is prohibitively monolithic, which is often the first thing that comes to mind when people think of monorepos. Keep reading, and you'll see that a good monorepo is the opposite of monolithic.
A good monorepo is the opposite of monolithic! Read more about this and other misconceptions in the article on “Misconceptions about Monorepos: Monorepo != Monolith”.
Isolation buys autonomy. But autonomy has a compounding cost.
The opposite of a monorepo is often called a “polyrepo”: each team or application lives in its own repository, with its own dependencies, tooling, build artifact, and CI pipeline.
Organizations adopt polyrepos to give teams autonomy: independent choices about libraries, release cadence, and contribution rules. But this autonomy comes through isolation, and isolation doesn't eliminate the need for integration. It just delays it. Shared contracts still need to align. Breaking changes still need coordinating. The feedback just arrives later in the development cycle, when it's harder and more expensive to act on.
Cumbersome code sharing
Sharing code across repos means setting up a dedicated repository, CI, package publishing, and version management. Consumers must reconcile incompatible versions of shared dependencies. The overhead discourages sharing in the first place.
Share code without publishing overhead
No versioned packages needed when all consumers are in the same repo. Sharing a new library is as simple as creating a folder. Existing CI handles everything.
Significant code duplication
When sharing is too costly, teams reimplement common services and components in each repo. This multiplies maintenance, security patching, and quality control across every copy.
Single source of truth
Common services and components live in one place. Fix a bug once, every consumer gets the fix. No copies to track down.
Costly cross-repo changes
A bug in a shared library means multiple PRs across disconnected histories, sequenced merges, and compatibility gymnastics: beta releases, consumer upgrades, stable releases, repeat.
Atomic commits across projects
Everything works together at every commit. A breaking change in a shared library and the fix in every consumer land in the same PR. No sequenced merges, no compatibility dance.
Hard to enforce conventions
Each repo makes its own choices about tooling, dependencies, code structure, and documentation. Enforcing organizational standards means maintaining separate configs and review processes per repo. Drift is the default.
Enforceable conventions at scale
Organizational rules live in one place and apply everywhere: code style, dependency policies, repo structure, documentation standards. Tooling can enforce constraints automatically. Consistency is the default.
Repo boundaries act as walls for both humans and AI assistants. An AI agent cannot see beyond the repo boundary and has to rely on specs and docs rather than the actual implementation.
The path to fully leveraging AI agent capabilities.
An AI agent can only see the code inside the current repository. Everything beyond that boundary has to come from documentation, published type definitions, or manual explanations that may be incomplete or out of date.
The agent reads the actual implementation: real API handlers, real data types, real shared libraries. Plans are higher quality because they are based on the code itself.
When work spans multiple repos, the human becomes the bridge. You describe the API shape, point the agent to docs, explain what the other service expects. Context gets lost at every repo boundary.
No walls between projects. The agent navigates from frontend to backend to shared libraries directly. Context is discovered, not transferred. No manual handoff needed.
Refactoring, migrations, dependency upgrades: the tedious, error-prone work that teams keep postponing. AI agents are perfect for it, but repo boundaries limit what they can see and change. Cross-repo changes stay manual, slow, and fragile.
The agent has full access to apply changes across projects, run affected tests, and submit a consistent, atomic PR. Visibility and context make this possible, and so do quick, immediate feedback loops.
Breaking changes surface late. You publish to staging, wait for the downstream repo to update, and discover the failure in a new session with no context of what changed or why. The feedback cycle is slow and disconnected.
Change the backend and frontend tests break immediately. The agent knows why, because it made the change. It proposes a fix: update the frontend or make the API non-breaking. The whole loop happens in one session, with full context.
Full visibility, autonomously discoverable context, and instant feedback loops: the ingredients to leverage AI agents to their fullest.
Consolidating all your repos into one isn’t always feasible. Synthetic monorepos give you monorepo-level intelligence across existing repositories without moving code.
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.
For platform engineers and architects, no more manually cataloging and cross-referencing repos. Tooling on top of the graph enables conformance checking, impact analysis, and coordinated changes across boundaries.
For AI agents, the graph exposes metadata that lets them see beyond individual repo boundaries. Instead of operating at a local maximum within a single repo, agents can read cross-repo relationships and perform coordinated changes across polyrepos.
A synthetic monorepo doesn’t tear down the walls between repos. It creates tunnels through them, giving humans and AI agents the visibility to effectively work across boundaries.
Start getting monorepo benefits without changing how teams work. From there, deepen integration where it makes sense: start synthetic, migrate gradually, move at your own pace. Nx supports synthetic monorepos out of the box.
A monorepo is only as good as the tool that powers it. Here’s what you should expect.
Store and replay file and process output of tasks. On the same machine, you never build or test the same thing twice.
Share computation results across your entire organization. If a teammate already built it, you get the result instantly.
Distribute work across multiple machines while preserving the developer experience of running everything locally.
Determine which projects are affected by a given change and only run the relevant tasks. Skip everything else.
Break large tasks into fine-grained cacheable units. Each slice can be cached and distributed independently.
Automatically detect flaky tests, quarantine them, and re-run only what failed. Keep your CI signal clean.
Nx checks all these boxes. Compare tools →
AI agents are only as effective as the context they can access. An agent working inside a single repo with no visibility into related projects, no dependency graph, and no way to run cross-project tasks will produce isolated, often wrong results. It hits a ceiling quickly.
The difference compounds. Every feature, refactoring, and migration benefits from that structural advantage. If your teams are adopting AI tooling but your codebase isn’t set up for it, you’re leaving most of the value on the table.
A monorepo removes that ceiling. If you’re not ready for a full consolidation, a synthetic monorepo can be an incremental starting point.
Nx helps you get your codebase AI-ready, whether you’re starting from a monorepo, polyrepo, or somewhere in between.
A curated list of videos, podcasts, and articles to go deeper into monorepos.
Have a resource you think should be listed here? Open an issue and let us know!
