A monorepo is a single version controlled repository that holds several related projects, such as a web app, a mobile app, an API, and shared libraries. Each project can still be built, tested, and deployed independently.

Is a monorepo only for large companies?

No. Small teams often benefit most, because shared types, one pull request for a cross cutting change, and a single place to look for code reduce overhead. The tooling has become light enough for a two person team.

Do I need Nx or Turborepo to use a monorepo?

Not on day one. Plain workspaces from pnpm, npm, or yarn are enough to share packages. Add a build orchestrator like Turborepo or Nx when build and test times start to hurt.

When is a polyrepo the better choice?

Polyrepos fit when teams are truly independent, when services use different languages and release on different schedules, or when you need strict access control between codebases, such as with an outsourced vendor.

Can I migrate from polyrepo to monorepo later?

Yes. You can import repositories with their history using standard git tooling. It is easier to merge repositories later than to split a tangled monorepo, so starting simple is reasonable.

Monorepo vs Polyrepo: Which Code Structure Fits Your Startup?

Sooner or later every startup faces the same quiet decision: do we keep everything in one repository, or give each app and service its own? The choice rarely feels urgent when you have one developer and one product. Then you add a mobile app, an admin dashboard, a marketing site, and a background worker, and suddenly a single change to an API response means four pull requests in four places.

This guide compares a monorepo (one repository, many projects) with a polyrepo (one repository per project) in practical terms. We focus on what matters to small teams: speed of shipping, code sharing, CI cost, security, and how painful it is to change your mind later.

Defining the two approaches

In a monorepo, your web frontend, API, mobile app, and shared packages live in one git repository, usually in folders like apps/ and packages/. In a polyrepo setup, each of those is its own repository with its own history, issues, and release process.

Neither is "the modern way" or "the old way". Large companies run both successfully. The right answer depends on how your team works and how much code your projects genuinely share.

Where a monorepo helps

Shared code without publishing packages

In a polyrepo world, sharing a TypeScript type or a validation function means publishing a package, bumping its version in every consumer, and waiting for updates to roll through. In a monorepo, the shared package is a folder. Change it once and every app sees the update immediately. If your frontend and backend validate the same data, our guide on shared validation schemas with Zod shows how much duplication that removes.

Atomic changes

Renaming an API field and updating every client can be one pull request, reviewed once, merged once. There is no awkward window where the backend has shipped but the mobile app still expects the old shape.

Consistent tooling

One linting configuration, one TypeScript configuration, one set of scripts. New developers clone one repository and run one install command. Upgrading a dependency across all apps becomes a single task instead of a chore repeated per repository.

Easier discovery

Searching the whole codebase for a function name takes seconds. For small teams, where one person often touches the web, the API, and the mobile app in a single week, this visibility is worth a lot.

Where a monorepo hurts

CI gets slow if you do nothing. A naive pipeline rebuilds and retests everything on every commit. You need caching and "affected only" logic to avoid this.
Access control is coarse. Anyone who can read the repository can read all of it. If a contractor should only see the marketing site, a monorepo is awkward.
Tooling needs care. Dependency hoisting, workspace linking, and build ordering can produce confusing errors, especially with mobile toolchains like React Native that have strong opinions about module resolution.
Discipline is required. Without boundaries, packages start importing each other's internals and the monorepo becomes a big ball of mud with a nicer folder structure.
Release cadence coupling. If apps share a version history, teams need clear habits about what triggers a deployment of which app.

Where a polyrepo helps

Separate repositories give clear ownership. Each project has its own issues, permissions, release cycle, and CI configuration. Teams can pick different languages and toolchains without compromise. A Python machine learning service and a Node API have little reason to share a repository, and forcing them together adds friction.

Polyrepos also suit vendor relationships. If an external agency builds your mobile app, giving them a dedicated repository limits what they can see and makes handoff cleaner. Our article on source code ownership in outsourced development explains why repository structure and access matter when multiple parties are involved.

Where a polyrepo hurts

Cross repository changes are slow. One feature can require coordinated pull requests, and reviewers lack the full picture.
Version drift. Repositories slowly diverge in dependency versions, lint rules, and conventions.
Shared code becomes a project of its own. Publishing, versioning, and maintaining internal packages is real work that small teams underestimate.
Onboarding takes longer. New developers need to know which repositories exist, how they connect, and how to run them together.

A real-world example

Take an illustrative scenario: a four person startup builds a booking platform with a customer web app, a provider mobile app, a Node API, and a small admin panel. All four share data types: bookings, users, and payment statuses. In a polyrepo layout, every change to a booking field means touching four repositories and publishing a types package. The team spends noticeable time on coordination rather than features.

Moving to a monorepo with a shared packages/types and packages/validation folder removes most of that overhead. The same team could plausibly cut the number of pull requests per cross cutting change from four to one. The cost is a few days setting up workspaces and CI caching, which tends to pay back quickly when the apps are genuinely related.

Contrast that with a startup whose product is a Node API plus a separate Python data pipeline owned by a different engineer. Little code is shared, the release schedules differ, and a polyrepo keeps things simple.

Step by step: choosing and setting up your structure

List your deployable units. Write down every app, service, and library you have or will have in the next year.
Map what is shared. Mark types, validation, UI components, configuration, and utilities used by more than one unit. High overlap points toward a monorepo.
Check team and access boundaries. If outside parties need limited access, plan separate repositories for their pieces.
Check languages. A single language ecosystem, such as TypeScript across web, mobile, and API, makes a monorepo smooth. Mixed languages reduce the benefit.
Start with plain workspaces. Use pnpm workspaces or npm workspaces with apps/ and packages/ folders. Resist adding a heavy orchestrator until you feel pain.
Set package boundaries. Each package exposes a public entry point. Lint rules forbid deep imports into another package's internals.
Make CI affected aware. Configure your pipeline to build and test only what changed, with remote caching when available. Our walkthrough of CI/CD pipelines with GitHub Actions is a good base to extend.
Use code ownership files. A CODEOWNERS file routes reviews for each folder to the right people even inside one repository.
Review after six months. Check whether CI times, merge conflicts, and onboarding feel better or worse, and adjust.

Tooling options in plain language

Workspaces

Built into package managers, workspaces link local packages together so apps can import them like any other dependency. This is the foundation and is often enough for a long time.

Task runners and build caches

Tools such as Turborepo and Nx understand the dependency graph between packages. They run tasks in the right order, skip work that has not changed, and share cached results between developers and CI. You adopt them when your build or test time begins to slow the team down.

Deployment

Most hosting platforms support deploying a subfolder of a monorepo. Configure each app with its own root directory and build command so that a change to the admin panel does not redeploy the customer site.

Key benefits when a monorepo fits

Fewer coordination mistakes because related changes ship together.
Less duplicated code across web, mobile, and backend.
Faster onboarding with one clone and one setup process.
Simpler dependency upgrades done once for the whole product.
A clearer view of the system for founders and new engineers.

Mistakes to avoid

Adopting heavy tooling too early. If your build takes under a minute, you do not need a distributed cache.
Putting unrelated projects together just because they belong to the same company.
Skipping boundaries. Without rules, shared packages become dumping grounds.
Ignoring mobile quirks. Test your React Native or Flutter setup early inside the workspace, because bundler and native build tools can be fussy about symlinks and paths.
Treating the decision as permanent. You can merge repositories with history intact, and you can split a package out later if it needs its own life.

A simple decision rule

If most of your projects use the same language, are built by the same small team, and share data types or UI code, start with a monorepo using plain workspaces. If projects are owned by different teams, use different stacks, or involve outside vendors with limited access, keep separate repositories. When in doubt, begin with the simpler structure that avoids publishing internal packages, and revisit when real pain appears.

If you are planning a product with a web app, mobile app, and API and want the foundations set up cleanly from the start, our team can help through our web development services.

Questions to ask before you commit

Before you restructure anything, hold a short team discussion built around a few honest questions. How often does one feature touch more than one project? How many hours a month go into coordinating versions between repositories? Who needs access to which code, and could that be handled with folder level review rules instead of separate repositories? How long does a full build take today, and how long would it take with caching? Write the answers down. If the numbers show that coordination is your main cost, a monorepo is likely to help. If they show that your projects barely interact, leave them alone and spend your time on the product instead.

Also think about hiring. Candidates who have worked in a monorepo with good tooling often find it easy to contribute on day one, while a collection of many small repositories can take longer to understand. Neither is a reason to choose a structure by itself, but it is a useful tiebreaker when the technical case is balanced.

Conclusion

The monorepo versus polyrepo debate is less about ideology and more about how much your projects share and how your team collaborates. For most early stage products built by a small team in one language, a monorepo with simple workspaces removes friction and keeps everyone looking at the same picture. For independent services and vendor boundaries, separate repositories keep things tidy. Choose based on your actual overlap, keep boundaries clean, and treat the decision as one you can revisit as your product and team grow.

Frequently Asked Questions

What is a monorepo?: A monorepo is a single version controlled repository that holds several related projects, such as a web app, a mobile app, an API, and shared libraries. Each project can still be built, tested, and deployed independently.
Is a monorepo only for large companies?: No. Small teams often benefit most, because shared types, one pull request for a cross cutting change, and a single place to look for code reduce overhead. The tooling has become light enough for a two person team.
Do I need Nx or Turborepo to use a monorepo?: Not on day one. Plain workspaces from pnpm, npm, or yarn are enough to share packages. Add a build orchestrator like Turborepo or Nx when build and test times start to hurt.
When is a polyrepo the better choice?: Polyrepos fit when teams are truly independent, when services use different languages and release on different schedules, or when you need strict access control between codebases, such as with an outsourced vendor.
Can I migrate from polyrepo to monorepo later?: Yes. You can import repositories with their history using standard git tooling. It is easier to merge repositories later than to split a tangled monorepo, so starting simple is reasonable.