We host monthly webinars where we share the latest on how Nx enables large organizations to ship quickly without compromising quality, at scale. Miroslav Jonaš recently presented these ten essential monorepo myths, and we thought they were too good to keep to ourselves! Read through the myths here, or you can register to view the full recording.
Be sure to register for our next webinar so you don't miss out!
How Myths are Created
Monorepos have become increasingly popular in modern software development, but misconceptions about them persist. These myths often become the biggest obstacles to adoption, even when monorepos could significantly improve your team's workflow. Let's examine ten common myths and uncover the reality behind them.
Before diving into specific myths, it's worth understanding how these misconceptions emerge in the first place:
Shoehorning - Trying to force new concepts into old mental models that don't quite fit. Monorepos work differently than traditional multi-repo setups, and assuming they're identical leads to false conclusions.
The "Master Level" Trap - Skipping the documentation and jumping straight into implementation. When we overestimate how our existing expertise translates to new tools, we set ourselves up for failure.
Hammer Syndrome - Just because you have a powerful tool doesn't mean everything is a nail. Monorepos are powerful, but they're not the solution for every problem.
Myth #1: Monorepos are just monoliths
This is perhaps the most fundamental misconception. While both terms start with "mono," they represent completely different concepts.
The Reality: Monoliths are an architectural pattern where all code is tightly coupled into a single deployable unit. Monorepos are a source control strategy that can contain monoliths, microservices, micro frontends, or any combination thereof.
In fact, monorepos actually encourage modular architecture and loose coupling. If you think of a monolith as a headache, consider a monorepo as the pain killer that helps relieve it.
Myth #2: Monorepos are inherently slow
"Every change rebuilds everything. Pipelines choke. CI costs explode. Developers give up."
This myth stems from traditional systems that lack dependency awareness. Without understanding what's affected by a change, you're forced to rebuild and retest everything, leading to multi-hour pipelines and nightly tests.
The Reality: Modern monorepo tools provide dependency graphs that expose exactly what's been affected by your changes. You can filter work to only the subset of projects that actually need attention.
CI cost and performance depend primarily on pipeline design, not repository topology. With proper dependency handling and features like caching, monorepos can actually be faster and cheaper than polyrepos, especially when you're only running the subset of work that's truly necessary.
Myth #3: Monorepos can't scale beyond a certain point
"How big is too big? How many projects can you have before things become unbearably slow?"
This concern often comes with assumptions about synchronized deployments and impossible rollbacks. However, deployments and development are orthogonal concepts.
The Reality: The size of your monorepo doesn't dictate how or when you deploy applications. You can easily have deployment pipelines per project while treating each project as if it were in a separate repository, or take advantage of monorepo features. The choice is yours.
Scaling limitations are always a matter of tooling:
- Checkout too slow? Use partial checkout
- Type checking too slow? Implement project references
- Graph too convoluted? Your architecture needs attention
Myth #4: Monorepos don't work for polyglot or microservices
Without separate repositories, maintaining clear ownership and technology choices seems impossible. We're used to having full control over a project and assume that multiple programming languages and frameworks can't coexist successfully.
The Reality: In monorepos, each project can have its own build, runtime, and deployment pipeline as if it were in a completely separate repository. Teams can restrict access to their code and prevent unauthorized dependencies.
For example, the Nx codebase contains TypeScript, Rust, Go, Kotlin, and Python. You can use repository-wide conventions where they add value and define per-folder toolchains where they don't. The key is that monorepos provide optional standardization: you bring the benefits without forcing uniformity.
Myth #5: Adoption has to be a big bang
"We'd love to adopt a monorepo, but we just don't have time to block weeks or months of development for a full migration."
This assumption comes from painful memories of technology migrations.
The Reality: Migrating to monorepos doesn't have to be a big bang. Start with a single repo, turn on monorepo tooling, then import another repository while preserving the full Git history. Initially, treat them as separate repositories that happen to be collocated in the same Git repository.
As you add more pieces (shared libraries, services, etc.), you can gradually think about standardization, alignment, and creating joint pipelines. You don't have to place everything in the same monorepo immediately. Features like Polygraph allow you to see dependencies beyond single monorepo borders and run checks across several repositories as if they were one.
Myth #6: You're locked into lockstep versioning
Lockstep versioning means deploying everything simultaneously with aligned versions. Many popular open source tools publish lockstep versions, leading to the conclusion that it's unavoidable.
The Reality: Packages in monorepos can have independent versions and release cycles. Lockstep versioning is a choice, not a requirement imposed by the monorepo strategy.
Workspace-aware package managers and monorepo tools often include release tooling that enables you to:
You can implement continuous deployment where you deploy on every change, or decide when to deploy on a per-project, per-application basis.
Myth #7: There are no code boundaries or permission controls
In a huge repository with hundreds of projects and hundreds of people, it's understandable to assume things can get out of control. "Everyone can see all the code and change all the code because they have access to the same repository."
The Reality: Monorepo tools can provide better code boundaries and source control than traditional multi-repo setups. You can use:
- Path-based ownership and review rules (like CODEOWNERS files)
- Granular write controls enforced by branch protection or server-side policies
- Automated checks for code requiring approvals from owners
- Cross-boundary change validation
In polyrepos, while you might have security per repository, you can't know how published projects are used across the company. In a monorepo, you can absolutely restrict those usages and enforce architectural boundaries. Conformance rules help automate consistency across your organization.
Myth #8: Cognitive load is high & onboarding is painful
A massive repository seems too overwhelming for developers to navigate and understand, leading to painful onboarding.
The Reality: Proper tooling and organization make large codebases more manageable than scattered multi-repo setups. When you have unified tooling, you can:
- Set a single set of tools for testing and building
- Unify frameworks, libraries, and their versions
- Create a consistent developer environment
- Reduce overhead where developers spend less time on tooling decisions
- Focus on architecture and code quality
Monorepos enable better technical debt management by providing visibility across your entire codebase.
Myth #9: Dependency hell is worse in monorepos
With everything centralized, each project bringing its own dependencies seems to create unmanageable chaos.
The Reality: Centralization makes it easier to:
- Find duplicate dependencies and consolidate them
- Apply security patches organization-wide
- Spot incompatibilities between libraries
- Maintain allowed versions in a single place
- Run automated dependency updates
- Perform vulnerability scans for the entire organization
You can still make overrides when needed. If a legacy application needs to use a different version of React or Java, you can override it per project without affecting the rest of your monorepo.
Myth #10: AI doesn't work in large codebases
AI shines with single-file changes and simple prompts. But as projects grow and require changes across multiple files, AI fails more frequently.
The Reality: This isn't a limitation of large codebases. It's a consequence of how you're using AI. Giving AI the full context of a monorepo actually creates better results than polyrepos or single repositories.
Monorepo tools share valuable context with AI:
- How to use monorepo tooling
- In-depth insights about architecture, the graph, and connections
- Conventions for the codebase
- How to run tasks to validate changes
Learn more about how AI works better in monorepos, make your AI assistant smarter with Nx and watch our webinar on AI-assisted development in monorepos.
The Path Forward
Monorepo myths stem from misunderstanding how modern tooling solves traditional problems. The key takeaways:
Don't Believe the Myths: Monorepo tools have ready solutions for virtually all challenges. They bring serious quality of life and developer experience improvements.
Start Incrementally: You don't have to merge everything into a single repo on day one. Even having several monorepos is better than an unmaintainable mess with polyrepos. With features like Polygraph, you can combine the benefits of polyrepos and monorepos.
Leverage AI Properly: Provide your AI agents with the right context. Clear structure and valuable context can elevate them from junior developer to principal architect level.
Value Your Time: Your time at the company and your developer experience are valuable. Why waste them on tooling maintenance, long build pipelines, and subpar experiences? Share with stakeholders the time spent on non-business tasks, CI instabilities, and idle waiting. Ask yourself: "Does my company want me doing this? How much does it cost? Can we do better?"
Learn More
Want to explore how monorepos can transform your development workflow? Here are some helpful resources: