Web & App Development

Monorepo vs Polyrepo: Which Repository Layout Should You Use?

Shubham Parmar7 min read
Monorepo vs Polyrepo — repository layout decision guide banner

In short: Use a monorepo when related apps share code and you want one pull request to update an API and every consumer. Use a polyrepo when the projects are independent, or when access control has to be a repository boundary. A monorepo is not a monolith, and it does not force every app to deploy at the same time.

What this means for you

  • If a web app, a mobile app, and an API share types, start in one repository.
  • Split into separate repositories when teams must not see each other's code, or when the products barely share anything.
  • Add affected-build tooling once CI starts rebuilding the whole repository on every change. Do not adopt Bazel just because the repo is large.

Teams argue about this as if it were a philosophy. It is a layout. The question is whether a change to shared code should land with its consumers in one pull request, or travel as a versioned package that each repository adopts later.

What each layout actually is

Monorepo

A monorepo is one Git repository that contains more than one project: a web app, an API, a shared UI kit, a types package. They are versioned together. They are not required to ship together. Nx's comparison makes that distinction explicit: projects build from the same commit, and each artifact can still deploy on its own schedule.

Polyrepo

A polyrepo is the layout most teams start from without naming it. Each app or service has its own repository, its own CI config, and its own permission boundary. Shared code leaves the repo as a published package. A consumer updates when someone bumps the version. That independence is the feature. The cost is that one logical change becomes several pull requests and a release.

This is not the monolith decision

A monolith is one deployable application. A monorepo is one repository. You can put a monolith in its own repo, or put twelve services in one repo and deploy them separately. You can also split a monolith across repositories and gain none of the isolation you wanted, because the code still has to change together. If the open question is service boundaries, that is a different guide: monolith vs microservices. Repository layout comes after you know which projects actually share code.

When a monorepo is the better default

Vercel's production-monorepo guide puts the cutoff in practical terms. Choose one repository when several apps share UI, utilities, or types, when cross-project changes are common, and when you want one toolchain for TypeScript, lint, and tests. Their rule of thumb: if the projects share more than configuration, a monorepo is likely the fit, and if you are unsure, start there. Splitting later is painful, but merging repositories while keeping history is worse.

That matches how a product with one API and two clients actually changes. A field rename on the API should update the web client and the mobile client in the same change. In a polyrepo, that rename is a package release plus two consumer upgrades, and one of them will lag. On an early product this shows up immediately. Our MVP development guide is about scoping the first release. The repository choice is part of that scope: one repo until a second, genuinely separate product appears.

When a polyrepo is the honest choice

Nx lists the cases where separate repositories are the point, not an accident. Strict repository-level access control is a hard requirement, or the teams share little code and nothing should force them to move together. Vercel adds different tech stacks that cannot share tooling, and products with different release cycles and no coordination.

Folder permissions inside a monorepo are not the same thing. People with clone access can still read the tree. If a contractor, a client team, or a regulated workload must not see another product's source, that is a repository boundary. Pretending a CODEOWNERS file solves it creates an audit problem later.

What breaks as the monorepo grows

The failure mode is CI, not Git. One pipeline that rebuilds every package on every commit gets slow, and people start skipping checks. The fix is to build what changed. Workspace tools (pnpm, npm, or Yarn workspaces) link packages on disk. A task runner such as Turborepo or Nx adds caching and affected-project detection so a web-only change does not rebuild the API.

Bazel is a different tier. Nx's comparison with Bazel argues that hermetic, reproducible builds pay off for large polyglot codebases that can staff build-system maintenance, and that a JS/TS-first team can get caching and affected builds without that migration. That page is a vendor's comparison, so treat the staffing claim as Nx's position, not an independent benchmark. The practical reading is enough: do not adopt a Google-scale build system because the repository feels big. Adopt it when several languages must build reproducibly and someone owns that system.

CI hosting is a separate choice. GitHub Actions vs GitLab CI vs Jenkins still applies inside a monorepo. The layout only changes how many workflow files you maintain, and whether one workflow can see every project.

A practical decision

SignalFavors
Web, mobile, and API share types or UI and change togetherMonorepo
A shared library should not drift across unpublished versionsMonorepo
One lint, test, and TypeScript setup should apply everywhereMonorepo
Products share almost no code and release on unrelated schedulesPolyrepo
Some people must be unable to read another product's sourcePolyrepo
Stacks are different enough that shared tooling would be fictionPolyrepo

How we set this on a build

On web and app development work, the default for a product that shares an API across clients is one repository, with a workspace and a CI job that builds what changed. We split a repository out when access control or a separate product makes the share dishonest. How long a move between layouts takes depends on how many repositories exist, how shared code is published today, and how much CI has to change. That is scoped in discovery, not quoted as a fixed timeline.

Frequently asked questions

What is a monorepo?

A monorepo is one Git repository that holds multiple projects — apps, services, and shared libraries — versioned together. It is not a monolith. A monorepo can contain many independently deployable services. The repository is shared. The deploy schedule does not have to be.

What is a polyrepo?

A polyrepo gives each project its own Git repository, with its own permissions, CI pipeline, and release cadence. Shared code is published as a versioned package instead of imported from a neighboring folder, so a change to a shared library becomes a release that each consumer adopts on its own.

When should you choose a monorepo?

Choose a monorepo when related apps share code, types, or UI and you often change an API and its consumers in the same pull request. Nx and Vercel both describe that atomic change, plus one toolchain, as the main reason to keep those projects in one repository.

When should you choose a polyrepo?

Choose a polyrepo when projects share little code, teams must not see each other's source, or the stacks and release cadences are so different that a shared repository would only add coordination. Repository-level access control is the requirement folder permissions only approximate.

Does a monorepo force every app to deploy together?

No. Projects can build from the same commit and still deploy on their own schedule. What a monorepo does force, as Nx describes it, is that every project builds against the latest shared code, so consumers stay current with a shared library instead of drifting across package versions.

Sources

  • Nx: Monorepo vs Polyrepo — The decision table: atomic changes and shared tooling versus team isolation and repository-level access control, and the point that a monorepo does not force a single deploy.
  • Vercel: Monorepos vs Polyrepos — When to choose each layout, and the advice to start in a monorepo when the projects share more than configuration.
  • Nx: Nx vs Bazel — Nx's own comparison of a JS/TS task runner against Bazel for large polyglot codebases that can staff a dedicated build team.

Need help putting this into practice?

Tech Programmer builds and ships this work for startups and enterprises. Tell us what you are trying to do and we will tell you what it takes.

Related reading