Monorepo vs polyrepo — the 2025 engineering decision

{ "title": "Scaling Code: The Case for Monorepos in 2025", "subtitle": "Modern tooling has eliminated the scaling overhead that once made polyrepos the default choice for growing teams.", "content": "The average engineer at a Fortune 500 company loses 4.2 hours per week to dependency management across disjointed repositories. This tax is silent but compounding. By the time a startup reaches 50 engineers, the cost of maintaining cross-repo consistency exceeds the cost of the actual features being built.\n\nTwenty years ago, Google chose the monorepo. Ten years ago, the industry mocked this as a Google-only luxury. In 2025, the tooling gap has closed. If you are starting a project today and choose a polyrepo, you are choosing intentional friction.\n\n## The Polyrepo Tax\n\nPolyrepos create an illusion of autonomy. Teams believe they move faster because they own their package.json or go.mod files. This is a local optimization that leads to global failure. \n\nWhen you need to update a shared logging library across 40 repositories, you face a miserable sequence of events. You must open 40 pull requests. You must wait for 40 CI pipelines to run. You must nag 40 sets of owners to merge. \n\nIn a monorepo, this is a single commit. You change the library and the callers in one atomic operation. The CI verifies the entire system immediately. If it breaks, it never merges. This is atomic refactoring, and it is the only way to maintain a modern codebase.\n\n## Versioning Is Counterproductive\n\nInternal versioning is a waste of engineering cycles. In a polyrepo world, teams treat internal dependencies like third-party libraries. They use Semantic Versioning (SemVer) for code that is developed by the person sitting across the hall.\n\nThis leads to dependency hell. Service A uses lib-logger@2.1.0. Service B uses lib-logger@3.0.1. You now have two versions of the same code to maintain, patch, and understand. \n\nMonorepos enforce a Single Version Policy. Every component uses the latest version of every other component. You do not version internal code. You simply use it. If a change breaks a downstream consumer, the author of that change must fix the consumer. \n\n## Remote Build Caching\n\nThe primary argument against monorepos used to be build times. Cloning a 50GB repository is slow. Running tests for a million lines of code is slower. \n\nModern build systems like Turborepo, Nx, and Bazel solved this using directed acyclic graphs (DAGs). These tools understand which files affect which outputs. If you change apps/api/src/main.ts, the build system knows it does not need to retest apps/web or libs/ui-components.\n\n- Build outputs are cached locally and in the cloud.\n- CI runners download pre-built artifacts instead of compiling from scratch.\n- Only the affected subset of the graph runs on each PR.\n- Computation is never repeated across the team.\n\n## Repository Visualization\n\nAt git11, we analyze thousands of repositories. We see a clear pattern in repository health. Polyrepos often hide dead code. Because it is difficult to see who is using a library in another repo, engineers fear deleting things. \n\nMonorepos make code discovery trivial. You use grep or ripgrep. You see every usage of an interface. You see every implementation of a trait. \n\n1. Search for a pattern across the entire company code.\n2.

Identify every call site.\n3. Apply the change across the entire stack.\n4. Verify results with a single integrated test suite.\n\n## The Vendor Lock-In Trap\n\nMany teams choose polyrepos because they want to GitHub's native permissions. They want Team A to have write access to Repo A, and Team B to have write access to Repo B. This is a management solution to a technical problem.\n\nModern monorepos use CODEOWNERS files. In github/CODEOWNERS, you define paths:\n\napps/payments/ @fintech-team \nlibs/auth/ @security-team\n\nThis provides the same granularity without the overhead of managing 200 distinct Git configurations. You get the benefits of centralized visibility with the security of decentralized ownership.\n\n## Dependency Management in 2025\n\nManaging node_modules or vendor directories across multiple repos is a nightmare. Vulnerabilities like CVE-2024-XXXX require a coordinated response. In a polyrepo setup, your security team spends three days auditing 500 package-lock.json files.\n\nIn a monorepo, you check one lockfile. You run one update. You verify the fix across the entire fleet in one CI pass. The time to remediation drops from days to minutes. \n\n- pnpm workspaces manages symlinks for TypeScript nodes.\n- go workspaces handles multi-module Go development.\n- cargo workspaces manage Rust crates efficiently.\n\n## CI Pipeline Efficiency\n\nRunning 50 separate CI pipelines is more expensive than running one large, intelligent pipeline. Polyrepo CI often involves \"triggering downstreams.\" Repo A updates, which triggers a build in Repo B, which triggers a build in Repo C.\n\nThis creates a non-deterministic mess. You lose the ability to see the state of the system at a specific commit hash. In a monorepo, the git hash is the state of the entire system. \n\nWe recommend using github-actions with path filters. Only run the jobs located in path/to/service when those files change. Combine this with a tool like Bazel to achieve sub-second rebuilds on massive codebases.\n\n## Onboarding and Tooling\n\nNew hires in a polyrepo environment spend their first week asking for permissions. They need access to the API repo, the frontend repo, the shared types repo, and the infra repo. They have to run git clone twelve times.\n\nIn a monorepo, the onboarding command is one line: git clone. The developer environment is defined in a single docker-compose.yaml or devcontainer.json at the root. They are productive on day one because they have the entire context on their machine.\n\n## The Cost of Tooling\n\nYes, monorepos require a dedicated focus on tooling. You may eventually need an Infrastructure Engineer to maintain the build graph. This is often cited as a reason to avoid monorepos.\n\nThis is a fallacious argument. You are paying for that infrastructure engineer either way. In a polyrepo world, you pay for it in the form of every engineer spending 10% of their time fixing broken versions, manual syncing, and duplicating CI logic. \n\n## When to Choose Polyrepos\n\nThere are exactly two valid reasons to use a polyrepo in 2025. First, if you are building open-source plugins that must be distributed independently. Second, if your business units have zero shared code and zero shared deployment targets.\n\nIf you share a single data model, a single auth service, or a single UI library, you belong in a monorepo. The friction of the "repo per service" model is a relic of 2014-era microservices hype.\n\n## The Migration Path\n\nMoving to a monorepo does not require a weekend rewrite of your entire history. You can use git subtree or git filter-repo to merge existing repositories while preserving commit history.\n\n1. Create a new root repository.\n2. Move existing repos into /apps or /libs directories.\n3. Unify the build system (e.g., move to a single pnpm workspace).\n4. Delete the old repositories.\n\n## Building for AI\n\nAs we build at git11, we see how LLMs interact with code. AI-assisted coding is significantly more effective in a monorepo. An AI agent needs context to provide accurate suggestions. \n\nIf the LLM can see the interface definition in libs/shared and the implementation in apps/api simultaneously, the hallucination rate stays low. Polyrepos fragment the context window. It is significantly harder for an AI to help you refactor code when half of the logic is in a repository it cannot see.\n\nA single repository is a single source of truth for your entire engineering organization.", "tags": ["monorepo", "architecture", "devops"], "category": "engineering", "read_time": 7 }