1# Repository Structure
2 
3Detailed guidance on structuring a Turborepo monorepo.
4 
5## Workspace Configuration
6 
7### pnpm (Recommended)
8 
9```yaml
10# pnpm-workspace.yaml
11packages:
12  - "apps/*"
13  - "packages/*"
14```
15 
16### npm/yarn/bun
17 
18```json
19// package.json
20{
21  "workspaces": ["apps/*", "packages/*"]
22}
23```
24 
25## Root package.json
26 
27```json
28{
29  "name": "my-monorepo",
30  "private": true,
31  "packageManager": "[email protected]",
32  "scripts": {
33    "build": "turbo run build",
34    "dev": "turbo run dev",
35    "lint": "turbo run lint",
36    "test": "turbo run test"
37  },
38  "devDependencies": {
39    "turbo": "latest"
40  }
41}
42```
43 
44Key points:
45 
46- `private: true` - Prevents accidental publishing
47- `packageManager` - Enforces consistent package manager version
48- **Scripts only delegate to `turbo run`** - No actual build logic here!
49- Minimal devDependencies (just turbo and repo tools)
50 
51## Always Prefer Package Tasks
52 
53**Always use package tasks. Only use Root Tasks if you cannot succeed with package tasks.**
54 
55```json
56// packages/web/package.json
57{
58  "scripts": {
59    "build": "next build",
60    "lint": "eslint .",
61    "test": "vitest",
62    "typecheck": "tsc --noEmit"
63  }
64}
65 
66// packages/api/package.json
67{
68  "scripts": {
69    "build": "tsc",
70    "lint": "eslint .",
71    "test": "vitest",
72    "typecheck": "tsc --noEmit"
73  }
74}
75```
76 
77Package tasks enable Turborepo to:
78 
791. **Parallelize** - Run `web#lint` and `api#lint` simultaneously
802. **Cache individually** - Each package's task output is cached separately
813. **Filter precisely** - Run `turbo run test --filter=web` for just one package
82 
83**Root Tasks are a fallback** for tasks that truly cannot run per-package:
84 
85```json
86// AVOID unless necessary - sequential, not parallelized, can't filter
87{
88  "scripts": {
89    "lint": "eslint apps/web && eslint apps/api && eslint packages/ui"
90  }
91}
92```
93 
94## Root turbo.json
95 
96```json
97{
98  "$schema": "https://v2-9-12.turborepo.dev/schema.json",
99  "tasks": {
100    "build": {
101      "dependsOn": ["^build"],
102      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
103    },
104    "lint": {},
105    "test": {
106      "dependsOn": ["build"]
107    },
108    "dev": {
109      "cache": false,
110      "persistent": true
111    }
112  }
113}
114```
115 
116With `futureFlags.globalConfiguration`, global settings move under a `global` key:
117 
118```json
119{
120  "$schema": "https://v2-9-12.turborepo.dev/schema.json",
121  "futureFlags": { "globalConfiguration": true },
122  "global": {
123    "inputs": ["tsconfig.json"],
124    "env": ["CI"]
125  },
126  "tasks": {
127    "build": {
128      "dependsOn": ["^build"],
129      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
130    },
131    "lint": {},
132    "test": {
133      "dependsOn": ["build"]
134    },
135    "dev": {
136      "cache": false,
137      "persistent": true
138    }
139  }
140}
141```
142 
143## Directory Organization
144 
145### Grouping Packages
146 
147You can group packages by adding more workspace paths:
148 
149```yaml
150# pnpm-workspace.yaml
151packages:
152  - "apps/*"
153  - "packages/*"
154  - "packages/config/*" # Grouped configs
155  - "packages/features/*" # Feature packages
156```
157 
158This allows:
159 
160```
161packages/
162├── ui/
163├── utils/
164├── config/
165│   ├── eslint/
166│   ├── typescript/
167│   └── tailwind/
168└── features/
169    ├── auth/
170    └── payments/
171```
172 
173### What NOT to Do
174 
175```yaml
176# BAD: Nested wildcards cause ambiguous behavior
177packages:
178  - "packages/**" # Don't do this!
179```
180 
181## Package Anatomy
182 
183### Minimum Required Files
184 
185```
186packages/ui/
187├── package.json    # Required: Makes it a package
188├── src/            # Source code
189│   └── button.tsx
190└── tsconfig.json   # TypeScript config (if using TS)
191```
192 
193### package.json Requirements
194 
195```json
196{
197  "name": "@repo/ui", // Unique, namespaced name
198  "version": "0.0.0", // Version (can be 0.0.0 for internal)
199  "private": true, // Prevents accidental publishing
200  "exports": {
201    // Entry points
202    "./button": "./src/button.tsx"
203  }
204}
205```
206 
207## TypeScript Configuration
208 
209### Shared Base Config
210 
211Create a shared TypeScript config package:
212 
213```
214packages/
215└── typescript-config/
216    ├── package.json
217    ├── base.json
218    ├── nextjs.json
219    └── library.json
220```
221 
222```json
223// packages/typescript-config/base.json
224{
225  "compilerOptions": {
226    "strict": true,
227    "esModuleInterop": true,
228    "skipLibCheck": true,
229    "moduleResolution": "bundler",
230    "module": "ESNext",
231    "target": "ES2022"
232  }
233}
234```
235 
236### Extending in Packages
237 
238```json
239// packages/ui/tsconfig.json
240{
241  "extends": "@repo/typescript-config/library.json",
242  "compilerOptions": {
243    "outDir": "dist",
244    "rootDir": "src"
245  },
246  "include": ["src"],
247  "exclude": ["node_modules", "dist"]
248}
249```
250 
251### No Root tsconfig.json
252 
253You likely don't need a `tsconfig.json` in the workspace root. Each package should have its own config extending from the shared config package.
254 
255## ESLint Configuration
256 
257### Shared Config Package
258 
259```
260packages/
261└── eslint-config/
262    ├── package.json
263    ├── base.js
264    ├── next.js
265    └── library.js
266```
267 
268```json
269// packages/eslint-config/package.json
270{
271  "name": "@repo/eslint-config",
272  "exports": {
273    "./base": "./base.js",
274    "./next": "./next.js",
275    "./library": "./library.js"
276  }
277}
278```
279 
280### Using in Packages
281 
282```js
283// apps/web/.eslintrc.js
284module.exports = {
285  extends: ["@repo/eslint-config/next"]
286};
287```
288 
289## Lockfile
290 
291A lockfile is **required** for:
292 
293- Reproducible builds
294- Turborepo to understand package dependencies
295- Cache correctness
296 
297Without a lockfile, you'll see unpredictable behavior.
298