Monorepo vs Polyrepo
debt(d7/e7/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints state automated=no, and while tools like nx, turborepo, and git can surface symptoms (e.g. unscoped rebuilds, version conflicts), none of them flag the architectural misuse itself. A team suffering from poor monorepo setup — no build caching, blurred package boundaries — only discovers the pain through degraded CI times and coordination overhead, not through any automated check.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix is high-level guidance rather than a single-line patch. Correcting a poorly structured monorepo (adding workspace tooling, enforcing module boundaries, introducing build caching, untangling shared dependencies) touches CI pipelines, package manifests, and team process across all packages simultaneously. Reversing course from monorepo to polyrepo — or vice versa — is a significant cross-cutting migration.
Closest to 'strong gravitational pull' (e7). The applies_to covers both web and cli contexts broadly, and the tags include architecture, devops, tooling, and team-process — signalling wide reach. Every future CI change, dependency upgrade, package addition, and deployment decision is shaped by the monorepo structure. Common mistakes like shared forced upgrades and missing workspace tooling create a persistent productivity tax that every maintainer feels.
Closest to 'notable trap — a documented gotcha most devs eventually learn' (t5). The misconception field explicitly names it: developers assume a monorepo forces tight coupling, when in reality coupling is governed by module boundaries, not repository boundaries. This leads teams to either avoid monorepos unnecessarily or adopt them and then fail to enforce boundaries, treating the repo as a monolith — a well-known, documented trap that most developers encounter once they work in larger codebases.
Also Known As
TL;DR
Explanation
A monorepo hosts multiple PHP packages, microservices, or applications in a single git repository. Benefits: atomic cross-service commits (change an API and its consumers in one PR), shared tooling and CI configuration, easier code sharing and refactoring across packages, unified dependency management. Challenges: repo size grows large, CI must run only affected tests (tools like Nx, Turborepo, or GitHub Actions path filters), and access control is coarser-grained. Polyrepos give each service independent versioning, deployment, and access control — better for teams that need autonomy, or when services have genuinely separate lifecycles. PHP monorepo tooling: symplify/monorepo-builder for synchronising composer.json files across packages; Composer path repositories for local package linking.
Common Misconception
Why It Matters
Common Mistakes
- No build caching — CI rebuilds every package on every commit regardless of what changed.
- Treating a monorepo as a monolith — packages should still have clear boundaries and independent versioning.
- Not using workspace tools (Turborepo, Nx, Composer workspaces) — manual management is error-prone.
- Shared dependencies that force all packages to upgrade together — defeats package independence.
Code Examples
# Monorepo without caching — rebuilds everything on every commit:
# packages/api changed
# CI runs: build:api build:web build:mobile build:docs
# Only api needed rebuilding — wasted 10 minutes
# With Turborepo cache:
# build:api — cache miss, runs (1 min)
# build:web — cache hit, skipped
# build:mobile — cache hit, skipped// PHP monorepo with multiple packages managed by Composer
// Structure:
// packages/
// core/ composer.json, src/, tests/
// payments/ composer.json, src/, tests/
// notifications/composer.json, src/, tests/
// composer.json (root — manages all packages)
// root composer.json:
{
"repositories": [
{"type": "path", "url": "packages/*"}
],
"require": {
"myapp/core": "@dev",
"myapp/payments": "@dev",
"myapp/notifications": "@dev"
}
}
// Run tests across all packages:
$ find packages -name phpunit.xml | xargs -I{} dirname {} | xargs -I{} bash -c 'cd {} && vendor/bin/phpunit'
// Tool: https://github.com/symplify/monorepo-builder
$ vendor/bin/monorepo-builder release 2.5.0 // bumps all package versions