1# Creating Internal Packages
2 
3How to create and structure internal packages in your monorepo.
4 
5## Package Creation Checklist
6 
71. Create directory in `packages/`
82. Add `package.json` with name and exports
93. Add source code in `src/`
104. Add `tsconfig.json` if using TypeScript
115. Install as dependency in consuming packages
126. Run package manager install to update lockfile
13 
14## Package Compilation Strategies
15 
16### Just-in-Time (JIT)
17 
18Export TypeScript directly. The consuming app's bundler compiles it.
19 
20```json
21// packages/ui/package.json
22{
23  "name": "@repo/ui",
24  "exports": {
25    "./button": "./src/button.tsx",
26    "./card": "./src/card.tsx"
27  },
28  "scripts": {
29    "lint": "eslint .",
30    "check-types": "tsc --noEmit"
31  }
32}
33```
34 
35**When to use:**
36 
37- Apps use modern bundlers (Turbopack, webpack, Vite)
38- You want minimal configuration
39- Build times are acceptable without caching
40 
41**Limitations:**
42 
43- No Turborepo cache for the package itself
44- Consumer must support TypeScript compilation
45- Can't use TypeScript `paths` (use Node.js subpath imports instead)
46 
47### Compiled
48 
49Package handles its own compilation.
50 
51```json
52// packages/ui/package.json
53{
54  "name": "@repo/ui",
55  "exports": {
56    "./button": {
57      "types": "./src/button.tsx",
58      "default": "./dist/button.js"
59    }
60  },
61  "scripts": {
62    "build": "tsc",
63    "dev": "tsc --watch"
64  }
65}
66```
67 
68```json
69// packages/ui/tsconfig.json
70{
71  "extends": "@repo/typescript-config/library.json",
72  "compilerOptions": {
73    "outDir": "dist",
74    "rootDir": "src"
75  },
76  "include": ["src"],
77  "exclude": ["node_modules", "dist"]
78}
79```
80 
81**When to use:**
82 
83- You want Turborepo to cache builds
84- Package will be used by non-bundler tools
85- You need maximum compatibility
86 
87**Remember:** Add `dist/**` to turbo.json outputs!
88 
89## Defining Exports
90 
91### Multiple Entrypoints
92 
93```json
94{
95  "exports": {
96    ".": "./src/index.ts", // @repo/ui
97    "./button": "./src/button.tsx", // @repo/ui/button
98    "./card": "./src/card.tsx", // @repo/ui/card
99    "./hooks": "./src/hooks/index.ts" // @repo/ui/hooks
100  }
101}
102```
103 
104### Conditional Exports (Compiled)
105 
106```json
107{
108  "exports": {
109    "./button": {
110      "types": "./src/button.tsx",
111      "import": "./dist/button.mjs",
112      "require": "./dist/button.cjs",
113      "default": "./dist/button.js"
114    }
115  }
116}
117```
118 
119## Installing Internal Packages
120 
121### Add to Consuming Package
122 
123```json
124// apps/web/package.json
125{
126  "dependencies": {
127    "@repo/ui": "workspace:*" // pnpm/bun
128    // "@repo/ui": "*"         // npm/yarn
129  }
130}
131```
132 
133### Run Install
134 
135```bash
136pnpm install  # Updates lockfile with new dependency
137```
138 
139### Import and Use
140 
141```typescript
142// apps/web/src/page.tsx
143import { Button } from '@repo/ui/button';
144 
145export default function Page() {
146  return <Button>Click me</Button>;
147}
148```
149 
150## One Purpose Per Package
151 
152### Good Examples
153 
154```
155packages/
156├── ui/                  # Shared UI components
157├── utils/               # General utilities
158├── auth/                # Authentication logic
159├── database/            # Database client/schemas
160├── eslint-config/       # ESLint configuration
161├── typescript-config/   # TypeScript configuration
162└── api-client/          # Generated API client
163```
164 
165### Avoid Mega-Packages
166 
167```
168// BAD: One package for everything
169packages/
170└── shared/
171    ├── components/
172    ├── utils/
173    ├── hooks/
174    ├── types/
175    └── api/
176 
177// GOOD: Separate by purpose
178packages/
179├── ui/          # Components
180├── utils/       # Utilities
181├── hooks/       # React hooks
182├── types/       # Shared TypeScript types
183└── api-client/  # API utilities
184```
185 
186## Config Packages
187 
188### TypeScript Config
189 
190```json
191// packages/typescript-config/package.json
192{
193  "name": "@repo/typescript-config",
194  "exports": {
195    "./base.json": "./base.json",
196    "./nextjs.json": "./nextjs.json",
197    "./library.json": "./library.json"
198  }
199}
200```
201 
202### ESLint Config
203 
204```json
205// packages/eslint-config/package.json
206{
207  "name": "@repo/eslint-config",
208  "exports": {
209    "./base": "./base.js",
210    "./next": "./next.js"
211  },
212  "dependencies": {
213    "eslint": "^8.0.0",
214    "eslint-config-next": "latest"
215  }
216}
217```
218 
219## Common Mistakes
220 
221### Forgetting to Export
222 
223```json
224// BAD: No exports defined
225{
226  "name": "@repo/ui"
227}
228 
229// GOOD: Clear exports
230{
231  "name": "@repo/ui",
232  "exports": {
233    "./button": "./src/button.tsx"
234  }
235}
236```
237 
238### Wrong Workspace Syntax
239 
240```json
241// pnpm/bun
242{ "@repo/ui": "workspace:*" }  // Correct
243 
244// npm/yarn
245{ "@repo/ui": "*" }            // Correct
246{ "@repo/ui": "workspace:*" }  // Wrong for npm/yarn!
247```
248 
249### Missing from turbo.json Outputs
250 
251```json
252// Package builds to dist/, but turbo.json doesn't know
253{
254  "tasks": {
255    "build": {
256      "outputs": [".next/**"]  // Missing dist/**!
257    }
258  }
259}
260 
261// Correct
262{
263  "tasks": {
264    "build": {
265      "outputs": [".next/**", "dist/**"]
266    }
267  }
268}
269```
270 
271## TypeScript Best Practices
272 
273### Use Node.js Subpath Imports (Not `paths`)
274 
275TypeScript `compilerOptions.paths` breaks with JIT packages. Use Node.js subpath imports instead (TypeScript 5.4+).
276 
277**JIT Package:**
278 
279```json
280// packages/ui/package.json
281{
282  "imports": {
283    "#*": "./src/*"
284  }
285}
286```
287 
288```typescript
289// packages/ui/button.tsx
290import { MY_STRING } from "#utils.ts"; // Uses .ts extension
291```
292 
293**Compiled Package:**
294 
295```json
296// packages/ui/package.json
297{
298  "imports": {
299    "#*": "./dist/*"
300  }
301}
302```
303 
304```typescript
305// packages/ui/button.tsx
306import { MY_STRING } from "#utils.js"; // Uses .js extension
307```
308 
309### Use `tsc` for Internal Packages
310 
311For internal packages, prefer `tsc` over bundlers. Bundlers can mangle code before it reaches your app's bundler, causing hard-to-debug issues.
312 
313### Enable Go-to-Definition
314 
315For Compiled Packages, enable declaration maps:
316 
317```json
318// tsconfig.json
319{
320  "compilerOptions": {
321    "declaration": true,
322    "declarationMap": true
323  }
324}
325```
326 
327This creates `.d.ts` and `.d.ts.map` files for IDE navigation.
328 
329### No Root tsconfig.json Needed
330 
331Each package should have its own `tsconfig.json`. A root one causes all tasks to miss cache when changed. Only use root `tsconfig.json` for non-package scripts.
332 
333### Avoid TypeScript Project References
334 
335They add complexity and another caching layer. Turborepo handles dependencies better.
336