1~
2When working on complex software projects, the choice between monorepo and polyrepo can significantly impact your team's productivity and code scalability. In this article, we analyze the differences, pros and cons of each approach, and help you understand which one is right for you.
3~
4## What are Monorepo and Polyrepo?
5~
6### Monorepo
7~
8A **monorepo** (monolithic repository) is a single repository that contains the source code for multiple projects, services, or packages, often related to each other.
9~
10```plaintext filename="Example Monorepo Structure"
11my-monorepo/
12  packages/
13    frontend/
14    backend/
15    shared/
16  package.json
17  turbo.json
18```
19~
20### Polyrepo
21~
22A **polyrepo** (multiple repositories) means that each project, service, or package has its own separate repository.
23~
24```plaintext filename="Example Polyrepo Structure"
25repos/
26  frontend/
27    package.json
28  backend/
29    package.json
30  shared/
31    package.json
32```
33~
34## Visual Difference
35~
36```mermaid
37flowchart TD
38    subgraph Monorepo
39        A1["frontend/"]
40        A2["backend/"]
41        A3["shared/"]
42    end
43    style Monorepo fill:#e0e7ff,stroke:#6366f1,stroke-width:2px
44```
45~
46```mermaid
47flowchart TD
48    subgraph Polyrepo
49        B1["frontend repo"]
50        B2["backend repo"]
51        B3["shared repo"]
52    end
53    style Polyrepo fill:#fee2e2,stroke:#ef4444,stroke-width:2px
54```
55~
56## Pros and Cons
57~
58### Monorepo
59~
60**Advantages:**
61- Makes code sharing easier (e.g., shared libraries).
62- Atomic refactoring across multiple projects.
63- Centralized management of dependencies and configurations.
64~
65**Disadvantages:**
66- Can become heavy as codebase grows.
67- Requires tools to manage partial builds/tests (e.g., Nx, Turborepo).
68~
69### Polyrepo
70~
71**Advantages:**
72- Each team/project is independent.
73- Easier to manage for small projects.
74- Allows for granular access policies.
75~
76**Disadvantages:**
77- Harder to share code without publishing packages.
78- Cross-repo refactoring is more complex.
79- Possible duplication of configurations.
80~
81## Practical Example: Monorepo with Turborepo
82~
83Suppose you want to create a monorepo with frontend and backend using Turborepo.
84~
85### 1. Initialize the monorepo
86~
87```bash
88npx create-turbo@latest
89```
90~
91### 2. Typical structure
92~
93```plaintext
94my-monorepo/
95  apps/
96    web/        # frontend Next.js
97    api/        # backend Node.js/Express
98  packages/
99    ui/         # shared component library
100    utils/      # shared functions
101  turbo.json
102  package.json
103```
104~
105### 3. Example workspace in `package.json`
106~
107```json
108{
109  "private": true,
110  "workspaces": [
111    "apps/*",
112    "packages/*"
113  ]
114}
115```
116~
117### 4. Example of importing a shared library
118~
119Suppose you have a function in `packages/utils/src/formatDate.ts`:
120~
121```ts
122// packages/utils/src/formatDate.ts
123export function formatDate(date: Date): string {
124  return date.toLocaleDateString('en-US');
125}
126```
127~
128In the frontend:
129~
130```ts
131// apps/web/pages/index.tsx
132import { formatDate } from '@myorg/utils';
133~
134export default function Home() {
135  return <div>Today is {formatDate(new Date())}</div>;
136}
137```
138~
139## When to Choose Monorepo?
140~
141- Medium-large teams working on multiple related projects.
142- Need to share code and perform large-scale refactoring.
143- Projects that grow quickly and require optimized builds/tests.
144~
145## When to Choose Polyrepo?
146~
147- Small or independent projects.
148- Separate teams working on different products.
149- Very restrictive access policies.
150~
151## Conclusion
152~
153There is no perfect solution for everyone. The choice depends on team size, project complexity, and collaboration needs. The important thing is to be aware of the trade-offs and choose the right tools to manage complexity.