GainHQ
Go back

Monorepo Vs Polyrepo: How To Choose The Right Setup

Monorepo Vs Polyrepo

by GainHQ Editorial Team | Aug 4, 2026 | Software Development Insights | Editorial policy


Table of Contents
  1. What is a monorepo?
  2. Does Google use a monorepo?
  3. Monorepo vs polyrepo: key differences
  4. Monorepo pros and cons
  5. Polyrepo pros and cons
  6. What tooling a monorepo needs
  7. Which should you choose?
  8. How to move from polyrepo to monorepo
  9. Do AI coding assistants work better in a monorepo?
  10. How GainHQ can help

A monorepo is a single version-control repository that holds several distinct projects, such as web and mobile apps, back-end services and shared libraries, with clear relationships between them. A polyrepo setup gives each project its own repository. Monorepos make sharing code and changing many projects at once easier, but they need good build tooling to stay fast. Polyrepos keep each project's build and access rules simple, but make shared changes and keeping dependencies in line harder.

Below: what a monorepo is in practice, how it differs from a polyrepo, what Google's well-known monorepo actually looks like, the tooling you need, and how to choose.

What is a monorepo?

A monorepo ("monolithic repository") is one repository that stores the code for many projects together, with one shared history. Nx, which builds monorepo tooling, defines it as "a single repository containing multiple distinct projects, with well-defined relationships between them" (Nx). The important words are distinct and well-defined: each project can still be built, tested and deployed on its own.

A small product company's monorepo might look like this (illustrative):

company-repo/
├── apps/
│   ├── web/            # customer web app
│   ├── admin/          # internal admin panel
│   └── mobile/         # React Native app
├── services/
│   ├── billing/        # billing API
│   └── notifications/  # email and push service
└── packages/
    ├── ui/             # shared design system
    ├── auth/           # shared login logic
    └── config/         # shared lint and TypeScript config

In a polyrepo setup, each of those eight folders would be its own repository, and ui, auth and config would be published as versioned packages for the others to install.

Is a monorepo the same as a monolith?

No. A monolith is an application architecture: one application deployed as a single unit. A monorepo is a way of storing code. A monorepo can hold a monolith, dozens of independently deployed microservices, or both. Nx makes the same distinction: projects in a monorepo stay separate and can be deployed on their own (Nx).

What is a polyrepo?

A polyrepo (also called multi-repo) setup gives each project, service or library its own repository, with its own history, pipeline and access rules. Teams share code by publishing packages to a registry and depending on specific versions. It is the default way many organisations grow, because each new project simply gets a new repository.

Does Google use a monorepo?

Yes, and it is the best-documented large example. In "Why Google Stores Billions of Lines of Code in a Single Repository" (Potvin and Levenberg, Communications of the ACM, 2016; Google Research listing), two Google engineers describe the repository as of January 2015:

Measure (January 2015)Figure
FilesAbout 1 billion
Source codeAbout 2 billion lines in 9 million unique source files
HistoryAbout 35 million commits
Size86 TB
Developers using itMore than 25,000
Human changes per workdayAbout 16,000
Automated changes per workdayAbout 24,000 (60% of the roughly 40,000 daily total, our calculation)

Google runs this on custom infrastructure: a version-control system called Piper, cloud workspaces called CitC, and trunk-based development, where most engineers work at the head of a single copy of the code with very few long-lived branches. Treat it as proof that monorepos can scale, not as a template. The figures are more than ten years old, and most teams will never need, or be able to build, Google's tooling.

Monorepo vs polyrepo: key differences

The main differences show up in code sharing, dependencies, changes across projects, builds and access control.

AreaMonorepoPolyrepo
Code sharingImport directly from shared folders; no publishing stepPublish and version packages; consumers upgrade on their own schedule
DependenciesUsually one version of each third-party library for everythingEach repo chooses its own versions; drift is common
Cross-project changesOne commit and one review can change an API and every callerSeveral pull requests across repos, merged in the right order
Builds and CINeeds tooling to build and test only what a change affectsEach pipeline is small and simple
Access controlCoarser by default; ownership enforced with tools such as CODEOWNERSNatural per-repo permissions
ReleasesProjects can still release independently, but all build against the latest shared codeFully independent release cycles
VisibilityEveryone can see and search all codeCode is spread out; cross-repo impact is harder to see

Monorepo pros and cons

Monorepos trade simpler collaboration for heavier tooling.

ProsCons
Shared code without publishing or versioningCI gets slow without "affected-only" builds and caching
Atomic changes across many projectsLarge repos can slow clones and everyday Git commands
One set of lint, test and dependency rulesA bad change to shared code can break many projects
Easier large-scale refactoringFine-grained access control takes extra setup
One place to search and onboardNeeds clear ownership rules to avoid a free-for-all

Polyrepo pros and cons

Polyrepos trade simpler repositories for more coordination.

ProsCons
Clear ownership and per-repo permissionsCross-repo changes need coordinated pull requests and releases
Small, fast, simple pipelinesShared code must be packaged and versioned
Teams choose their own tools and release paceDependency versions drift apart
Easy to open-source or hand over one projectDuplicated configuration and CI across repos
A problem in one repo stays in that repoHarder to see the impact of a change across the system

What tooling a monorepo needs

A monorepo stays fast when the tooling builds and tests only what changed, reuses results already computed, and lets developers check out only the parts they need. Plain Git can hold a monorepo, but these features come from build tools.

ToolWhat it isKey features (from official docs)
NxMonorepo build system, strongest in JavaScript and TypeScript, with plugins for othersAffected detection (run tasks only for projects impacted by a change), local and remote caching, distributed task execution via Nx Cloud
TurborepoBuild system for JavaScript and TypeScript monoreposWorks from existing package.json scripts plus one turbo.json; caching; Remote Cache; runs tasks in parallel "across all available cores"
BazelMulti-language build and test toolMany languages, extensible to others; builds with "100k+ source files"; hermetic builds through sandboxing; remote caching shared across developers and CI
Git sparse-checkoutBuilt into GitCheck out only selected directories ("cone mode"). Git still labels the command experimental
Git partial cloneBuilt into GitAvoid downloading unneeded objects up front, cutting clone time and disk use on very large repos
CODEOWNERS (GitHub)Ownership fileOwners are automatically asked to review changes to their folders; can be required before merging

As a rule of thumb, JavaScript and TypeScript teams usually start with Nx or Turborepo. Teams with several languages or very large codebases look at Bazel. Track build and CI times as part of your engineering KPIs, so you notice when the repository needs better tooling.

Which should you choose?

Choose a monorepo when your projects share a lot of code and change together. Choose a polyrepo when projects are independent, owned by separate teams, or need strict access separation.

SituationUsually betterWhy
Startup with one product (web, API, mobile)MonorepoShared types and UI; one change updates every client
Several products sharing a design system and authMonorepoShared packages change often; atomic updates help
Microservices owned by separate, autonomous teamsEitherMonorepo for shared contracts; polyrepo for independence
Open-source library with outside contributorsPolyrepoSimple to clone, contribute to and release
Contractors or partners who must see only part of the codePolyrepoPer-repo permissions are simpler and safer
Many languages and a very large codebaseMonorepo only with serious build toolingWithout affected builds and caching, CI slows down

Monorepo vs microservices is not an either/or choice. Microservices describe how your application is split and deployed. A monorepo describes where the code is stored. Many teams keep microservices in a monorepo so that shared contracts and libraries change together. Our guide to scalable software architecture covers the application side of that decision.

How to move from polyrepo to monorepo

Move in stages, starting with the projects that share the most code.

How to migrate from polyrepo to monorepo: map every dependency first, choose your build system early, preserve history and migrate in stages, update CI/CD and expect conflicts, lock down access control

  1. Map dependencies. List which repos depend on which shared packages and APIs. Start with a tightly linked group.
  2. Choose the build tool first. Set up affected builds and caching before moving many projects, or CI times will jump.
  3. Decide on history. Keep each repo's Git history if you need it for audits or debugging. Otherwise start fresh and archive the old repos as read-only.
  4. Migrate in waves. Move two or three projects, fix the pipeline, then continue. Keep the old repos frozen until the new setup is proven.
  5. Set ownership and rules. Add CODEOWNERS, branch protection and shared lint and test settings from day one.

Plan the move like any engineering change within your software development life cycle, with a rollback point, and schedule it across sprints during sprint planning, not as a weekend project.

Do AI coding assistants work better in a monorepo?

Monorepo tool vendors argue that they do. Nx says AI coding agents work better in monorepos because related code, context and feedback loops are in one place (Nx). The reasoning is plausible, since an assistant can only use the code it can see. However, we found no independent study that measures the effect, so treat it as a minor factor next to team structure and build tooling.

How GainHQ can help

GainHQ is a custom software development agency with more than 15 years of experience building software, more than 13 products delivered and a team of over 30 people. We also build and run our own products, Payrun and Gain.io. If you are setting up a new codebase or restructuring an existing one, see our services.

Frequently asked questions

What is a monorepo in simple terms?

A monorepo is one code repository that holds several separate projects, such as a web app, a mobile app, back-end services and shared libraries. Each project can still be built and deployed on its own, but they share one history and can share code directly.

What is a polyrepo?

A polyrepo, or multi-repo, setup gives each project or service its own repository. Teams share code by publishing versioned packages. It offers clear ownership and simple pipelines, at the cost of coordinating changes across repositories.

Is a monorepo the same as a monolith?

No. A monolith is an application deployed as a single unit. A monorepo is a way of storing code. A monorepo can contain a monolith, many independently deployed services, or both.

Does Google use a monorepo?

Yes. A 2016 Communications of the ACM article by Google engineers describes a single repository that, in January 2015, held about 2 billion lines of code in 9 million source files, used by more than 25,000 developers on custom tooling.

What are the disadvantages of a monorepo?

Without the right tooling, CI slows down because too much is rebuilt. Very large repositories can slow Git operations, a bad shared change can break many projects, and fine-grained access control needs extra setup.

Can microservices live in a monorepo?

Yes. Microservices describe how an application is split and deployed. A monorepo describes where the code lives. Many teams keep separately deployed services in one repository so that shared contracts and libraries change together.

What tools do you need for a monorepo?

Most teams use a build tool that runs tasks only for affected projects and caches results, such as Nx or Turborepo for JavaScript and TypeScript, or Bazel for multi-language codebases. Add CODEOWNERS for ownership, and Git sparse-checkout or partial clone for very large repositories.

When should I choose a polyrepo over a monorepo?

Choose a polyrepo when projects share little code, are owned by independent teams with their own release cycles, need strict access separation, or will be open-sourced or handed over separately.

Related Blogs