1# Dependency Management
2 
3Best practices for managing dependencies in a Turborepo monorepo.
4 
5## Core Principle: Install Where Used
6 
7Dependencies belong in the package that uses them, not the root.
8 
9```bash
10# Good: Install in specific package
11pnpm add react --filter=@repo/ui
12pnpm add next --filter=web
13 
14# Avoid: Installing in root
15pnpm add react -w  # Only for repo-level tools!
16```
17 
18## Benefits of Local Installation
19 
20### 1. Clarity
21 
22Each package's `package.json` lists exactly what it needs:
23 
24```json
25// packages/ui/package.json
26{
27  "dependencies": {
28    "react": "^18.0.0",
29    "class-variance-authority": "^0.7.0"
30  }
31}
32```
33 
34### 2. Flexibility
35 
36Different packages can use different versions when needed:
37 
38```json
39// packages/legacy-ui/package.json
40{ "dependencies": { "react": "^17.0.0" } }
41 
42// packages/ui/package.json
43{ "dependencies": { "react": "^18.0.0" } }
44```
45 
46### 3. Better Caching
47 
48Installing in root changes workspace lockfile, invalidating all caches.
49 
50### 4. Pruning Support
51 
52`turbo prune` can remove unused dependencies for Docker images.
53 
54## What Belongs in Root
55 
56Only repository-level tools:
57 
58```json
59// Root package.json
60{
61  "devDependencies": {
62    "turbo": "latest",
63    "husky": "^8.0.0",
64    "lint-staged": "^15.0.0"
65  }
66}
67```
68 
69**NOT** application dependencies:
70 
71- react, next, express
72- lodash, axios, zod
73- Testing libraries (unless truly repo-wide)
74 
75## Installing Dependencies
76 
77### Single Package
78 
79```bash
80# pnpm
81pnpm add lodash --filter=@repo/utils
82 
83# npm
84npm install lodash --workspace=@repo/utils
85 
86# yarn
87yarn workspace @repo/utils add lodash
88 
89# bun
90cd packages/utils && bun add lodash
91```
92 
93### Multiple Packages
94 
95```bash
96# pnpm
97pnpm add jest --save-dev --filter=web --filter=@repo/ui
98 
99# npm
100npm install jest --save-dev --workspace=web --workspace=@repo/ui
101 
102# yarn (v2+)
103yarn workspaces foreach -R --from '{web,@repo/ui}' add jest --dev
104```
105 
106### Internal Packages
107 
108```bash
109# pnpm
110pnpm add @repo/ui --filter=web
111 
112# This updates package.json:
113{
114  "dependencies": {
115    "@repo/ui": "workspace:*"
116  }
117}
118```
119 
120## Keeping Versions in Sync
121 
122### Option 1: Tooling
123 
124```bash
125# syncpack - Check and fix version mismatches
126npx syncpack list-mismatches
127npx syncpack fix-mismatches
128 
129# manypkg - Similar functionality
130npx @manypkg/cli check
131npx @manypkg/cli fix
132 
133# sherif - Rust-based, very fast
134npx sherif
135```
136 
137### Option 2: Package Manager Commands
138 
139```bash
140# pnpm - Update everywhere
141pnpm up --recursive typescript@latest
142 
143# npm - Update in all workspaces
144npm install typescript@latest --workspaces
145```
146 
147### Option 3: pnpm Catalogs (pnpm 9.5+)
148 
149```yaml
150# pnpm-workspace.yaml
151packages:
152  - "apps/*"
153  - "packages/*"
154 
155catalog:
156  react: ^18.2.0
157  typescript: ^5.3.0
158```
159 
160```json
161// Any package.json
162{
163  "dependencies": {
164    "react": "catalog:" // Uses version from catalog
165  }
166}
167```
168 
169## Internal vs External Dependencies
170 
171### Internal (Workspace)
172 
173```json
174// pnpm/bun
175{ "@repo/ui": "workspace:*" }
176 
177// npm/yarn
178{ "@repo/ui": "*" }
179```
180 
181Turborepo understands these relationships and orders builds accordingly.
182 
183### External (npm Registry)
184 
185```json
186{ "lodash": "^4.17.21" }
187```
188 
189Standard semver versioning from npm.
190 
191## Peer Dependencies
192 
193For library packages that expect the consumer to provide dependencies:
194 
195```json
196// packages/ui/package.json
197{
198  "peerDependencies": {
199    "react": "^18.0.0",
200    "react-dom": "^18.0.0"
201  },
202  "devDependencies": {
203    "react": "^18.0.0", // For development/testing
204    "react-dom": "^18.0.0"
205  }
206}
207```
208 
209## Common Issues
210 
211### "Module not found"
212 
2131. Check the dependency is installed in the right package
2142. Run `pnpm install` / `npm install` to update lockfile
2153. Check exports are defined in the package
216 
217### Version Conflicts
218 
219Packages can use different versions - this is a feature, not a bug. But if you need consistency:
220 
2211. Use tooling (syncpack, manypkg)
2222. Use pnpm catalogs
2233. Create a lint rule
224 
225### Hoisting Issues
226 
227Some tools expect dependencies in specific locations. Use package manager config:
228 
229```yaml
230# .npmrc (pnpm)
231public-hoist-pattern[]=*eslint*
232public-hoist-pattern[]=*prettier*
233```
234 
235## Lockfile
236 
237**Required** for:
238 
239- Reproducible builds
240- Turborepo dependency analysis
241- Cache correctness
242 
243```bash
244# Commit your lockfile!
245git add pnpm-lock.yaml  # or package-lock.json, yarn.lock
246```
247