Architecture
Monorepos: When They Help and When They Hurt
By Vivek Jalondhara · 2 min read
Published Aug 2025 · Updated
Shared code and atomic changes are great — until your build graph and CI become the bottleneck.
Monorepos shine when teams share code: one place for types, components, and utilities, and atomic commits across frontend and backend. Refactors that span services become a single reviewable change instead of a coordination nightmare.
The cost is tooling. Without good task caching and affected-graph builds, CI balloons and every developer pays for code they didn't touch. Invest in the build system early or the monorepo turns into a tax.
My rule: monorepo when code is genuinely shared and teams are aligned; separate repos when boundaries are hard and ownership is distinct. Structure should follow the team, not the other way around.
Share contracts without sharing server internals
Frontend and backend CRM modules can share public contract types while keeping database and secret-handling code on the server. This is an example layout, not a copy of the private repository.
Illustrative example · Directory layout · Simplified for explanation
apps/
web/
api/
packages/
contracts/ # Public request and response shapes
ui/ # Shared interface components
# The web app must not import database or credential modules.- Shared contract
- Independent web & API consumers
- Boundary checks
- Affected builds
Conceptual flow for the example above.
Tradeoff to keep in mind
A shared repository makes coordinated changes easier but can create accidental coupling. Define import boundaries and keep the build graph observable.