Step 1
Monorepo vs polyrepo
25 min
Monorepo vs polyrepo
Past three projects, structural decisions matter more than any individual library pick.
1. Monorepo
warragon/
├── frontend/
│ ├── pryzeet/
│ ├── admin/
│ └── codingstairs/
├── backend/
│ ├── java-backend/
│ └── python-backend/
├── infra/
└── docs/
2. Pros
- Atomic cross-repo changes
- Shared utilities/types in one place
- Unified tooling (pnpm · Docker · CI)
- Easy refactors (search/replace across repo)
- Team visibility
3. Cons
- Large repo (GB+)
- CI complexity (which project changed?)
- Access control harder
- Tooling locked (one Node version)
4. Polyrepo
Separate repos per project — pryzeet-web, pryzeet-api, admin-web …
5. Pros
- Small repos
- Access control per repo
- Independent releases
- Per-project tooling
6. Cons
- Cross-repo changes require multiple PRs
- Code duplication
- Version drift
- Poor discoverability
7. How to choose
| Situation | Pick |
|---|---|
| Solo / small team | monorepo |
| Tightly coupled frontend + API | monorepo |
| 100+ engineers | polyrepo or Nx/Turborepo monorepo |
| Strict access separation | polyrepo |
| Library publishing | polyrepo (semver) |
8. Tools
pnpm workspaces · Nx · Turborepo · Lerna.
# pnpm-workspace.yaml
packages:
- "frontend/*"
- "backend/*"
- "packages/*"
pnpm -F pryzeet add lodash
pnpm -F "./frontend/*" typecheck
9. CI optimisation
- uses: dorny/paths-filter@v3
id: changes
with:
filters: |
frontend_pryzeet: frontend/pryzeet/**
- if: steps.changes.outputs.frontend_pryzeet == 'true'
run: cd frontend/pryzeet && pnpm test
Turborepo handles cache + dep graph automatically.
10. Coupling discipline
Being in one repo doesn't grant cross-import rights. Enforce with eslint-plugin-boundaries.
11. Our monorepo (warragon)
9 services (7 frontends + 2 backends), 5 PostgreSQL instances, 3 Docker environments, one docs/ SSOT. Atomic PRs and unified Claude agent setup are the wins.
12. Gotchas
- Half-pushed changes
- Workspace dependency loops
- Over-splitting into 100 tiny packages
- External contributors / sensitive modules — use separate repo or CODEOWNERS
Closing
"Polyrepo from day one" is a common mistake. Start monorepo, split later when scale or access control demands.
Next
- 02-ssot-where