Your repository structure fundamentally affects how you approach code maintenance. Monorepos - single repositories containing multiple projects - present different maintenance challenges than polyrepos - many separate repositories for different projects. Neither is inherently better, but each requires different maintenance strategies.
Understanding how repository structure affects maintenance helps teams choose appropriate tools and processes. Whether you're maintaining a monorepo, polyrepo, or hybrid setup, the right approach makes maintenance manageable.
Monorepo Maintenance Challenges
Monorepos have distinct maintenance characteristics.
What Makes Monorepos Different
Everything in one place:
Monorepo structure:
/packages
/frontend
/backend
/shared-lib
/mobile
/services
/api
/worker
/scheduler
All code, one repository.
Monorepo Maintenance Challenges
Scale
Large codebases require more:
Monorepo challenge:
- Millions of lines of code
- Thousands of files
- Full scans take time
- Analysis is heavy
Scale creates performance challenges.
Shared Dependencies
Dependencies affect multiple projects:
Monorepo challenge:
- Update React → affects all React projects
- Version conflicts between projects
- Coordinated updates needed
Dependency management is complex.
Build Complexity
What to build when something changes:
Monorepo challenge:
- Change in shared-lib
- What needs rebuilding?
- What needs testing?
- Affected project detection
Impact analysis is challenging.
Ownership Boundaries
Multiple teams, one repository:
Monorepo challenge:
- Team A owns /packages/frontend
- Team B owns /services/api
- Cross-cutting changes
- CODEOWNERS complexity
Ownership is less natural than separate repos.
Monorepo Maintenance Strengths
Atomic Changes
Cross-cutting changes in one commit:
Monorepo strength:
- Update API and frontend together
- Single PR, single review
- No coordination across repos
Atomic changes simplify coordination.
Consistent Tooling
Same tools everywhere:
Monorepo strength:
- One CI configuration
- One linting setup
- One formatting standard
- Consistency by default
Tooling is naturally consistent.
Shared Code
Easy to share between projects:
Monorepo strength:
- Shared libraries are local
- No publishing needed
- Easy to update
Code sharing is frictionless.
Polyrepo Maintenance Challenges
Polyrepos have their own maintenance characteristics.
What Makes Polyrepos Different
Code distributed across repositories:
Polyrepo structure:
frontend-app (repo)
backend-api (repo)
shared-lib (repo)
mobile-app (repo)
Separate code, separate repositories.
Polyrepo Maintenance Challenges
Cross-Repo Coordination
Changes spanning repositories:
Polyrepo challenge:
- Update shared-lib
- Update frontend to use new version
- Update backend to use new version
- Coordinate multiple PRs
Coordination overhead is significant.
Inconsistent Tooling
Each repo can diverge:
Polyrepo challenge:
- Repo A: ESLint 8
- Repo B: ESLint 7
- Repo C: No linting
- Standards drift
Consistency requires effort.
Visibility
Seeing across repositories:
Polyrepo challenge:
- No single view of all code
- Organization health unclear
- Which repos have issues?
Organization-wide visibility is harder.
Duplication
Configuration repeated:
Polyrepo challenge:
- CI config in every repo
- Lint config in every repo
- Dockerfile in every repo
- Updates repeated N times
Maintenance multiplied by repo count.
Polyrepo Maintenance Strengths
Independence
Teams own their space:
Polyrepo strength:
- Team owns entire repo
- Independent decisions
- Independent release schedule
Clear ownership boundaries.
Simpler Individual Repos
Each repo is smaller:
Polyrepo strength:
- Faster CI per repo
- Simpler dependency tree
- Easier to understand
Individual repo complexity is lower.
Isolation
Problems are contained:
Polyrepo strength:
- Issue in one repo
- Doesn't affect others
- Blast radius limited
Isolation prevents cascading failures.
Comparing Maintenance Approaches
How maintenance differs by structure.
Dependency Management
| Factor | Monorepo | Polyrepo | |--------|----------|----------| | Update coordination | Automatic | Manual | | Version consistency | Enforced | Must manage | | Conflict resolution | At update time | At integration time | | Update frequency | Easier frequent | Harder frequent |
Monorepo simplifies dependency coordination.
Standards Enforcement
| Factor | Monorepo | Polyrepo | |--------|----------|----------| | Consistency | Natural | Requires effort | | Configuration | Single | Replicated | | Drift prevention | Built-in | Must monitor | | Tooling updates | Once | Per repo |
Monorepo provides natural consistency.
Scale and Performance
| Factor | Monorepo | Polyrepo | |--------|----------|----------| | Full scan | Expensive | Cheap per repo | | Incremental | Essential | Less critical | | CI time | Can be long | Short per repo | | Tool requirements | Heavy | Light |
Polyrepo has simpler per-repo characteristics.
Visibility
| Factor | Monorepo | Polyrepo | |--------|----------|----------| | Single view | Natural | Must aggregate | | Cross-project | Easy | Hard | | Organization health | One place | Aggregation needed |
Monorepo provides natural visibility.
Monorepo Maintenance Strategies
Effective approaches for monorepos.
Incremental Analysis
Only analyze what changed:
@devonair monorepo strategy:
- Detect changed files
- Determine affected projects
- Run relevant checks only
- Skip unchanged areas
Incremental approach handles scale.
Shared Configuration
Single source of truth:
@devonair monorepo strategy:
- Root-level config files
- Projects extend shared config
- Updates apply everywhere
Shared configuration ensures consistency.
Affected Project Detection
Smart impact analysis:
@devonair monorepo strategy:
- Change to shared-lib
- Determine who imports shared-lib
- Test affected projects
Smart detection reduces work.
Ownership Management
Clear boundaries within monorepo:
@devonair monorepo strategy:
- CODEOWNERS for directories
- Team-based routing
- Ownership-aware automation
Ownership within single repo.
Polyrepo Maintenance Strategies
Effective approaches for polyrepos.
Organization-Wide Scanning
Scan across repositories:
@devonair polyrepo strategy:
- Scan all repositories
- Aggregate findings
- Organization-level view
Aggregation provides visibility.
Shared Configuration Packages
Distribute configuration:
@devonair polyrepo strategy:
- @org/eslint-config package
- @org/prettier-config package
- Repos consume packages
Shared packages reduce duplication.
Synchronized Updates
Coordinate cross-repo changes:
@devonair polyrepo strategy:
- Dependency update in shared-lib
- PRs to all consuming repos
- Coordinated rollout
Automation handles coordination.
Repository Templates
Consistent repo setup:
@devonair polyrepo strategy:
- Standard repo template
- New repos start consistent
- Template updates propagate
Templates prevent drift.
Hybrid Approaches
Many organizations use both patterns.
Monorepo per Domain
Bounded monorepos:
Hybrid structure:
frontend-monorepo (web, mobile-web, design-system)
backend-monorepo (api, workers, integrations)
infrastructure-repo
Domain-scoped monorepos.
Polyrepo with Strong Standards
Polyrepo with monorepo benefits:
@devonair hybrid approach:
- Polyrepo structure
- Shared configurations
- Organization-wide scanning
- Coordinated updates
Polyrepo independence with consistency tools.
Choosing Tools for Your Structure
Tool requirements differ.
Monorepo Tool Requirements
@devonair monorepo tools need:
- Incremental analysis
- Affected detection
- Scale handling
- Performance optimization
Monorepo tools must handle scale.
Polyrepo Tool Requirements
@devonair polyrepo tools need:
- Multi-repo support
- Aggregation capability
- Cross-repo coordination
- Batch operations
Polyrepo tools must aggregate.
Getting Started
Maintain your repository structure effectively.
Understand your structure:
@devonair understand:
- Monorepo, polyrepo, or hybrid?
- How many repositories?
- What are the boundaries?
Apply appropriate strategies:
@devonair apply strategies:
- Monorepo: Focus on incremental, affected detection
- Polyrepo: Focus on aggregation, coordination
Choose appropriate tools:
@devonair choose tools:
- Support your structure
- Handle your scale
- Provide needed visibility
Repository structure shapes maintenance approach. Monorepos need incremental analysis and affected detection. Polyrepos need aggregation and coordination. Understanding your structure enables choosing the right strategies and tools for effective maintenance.
FAQ
Is monorepo or polyrepo better for maintenance?
Neither is universally better. Monorepos simplify consistency and coordination but require scale-handling tools. Polyrepos simplify individual repo complexity but require cross-repo coordination. Choose based on your organization's needs.
Can we migrate from polyrepo to monorepo?
Yes, but it's significant work. Consider domain-bounded monorepos as a middle ground. Migrate incrementally if you do. Ensure you have tooling that handles monorepo scale before migrating.
How do we maintain consistency across polyrepos?
Use shared configuration packages, organization-wide scanning, templates for new repos, and automated coordination tools. Consistency is achievable in polyrepo but requires explicit effort.
What if we have a mix of monorepo and polyrepo?
This is common. Apply monorepo strategies within monorepos and polyrepo strategies across repositories. Tools that support both patterns work best for hybrid setups.