Monorepo Structure
Developmentmonorepo-structureMonorepo Structure is an Agent Skill for development published in the dadbodgeoff/drift repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Set up a Turborepo + pnpm monorepo for sharing code between frontend, backend, and workers. One repo, multiple packages, shared types, parallel builds.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/dadbodgeoff/drift/blob/HEAD/drift v1 depreciated/skills/monorepo-structure/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/monorepo-structure, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Monorepo Structure
One repo, multiple packages, shared types, parallel builds.
When to Use This Skill
- Sharing code between frontend and backend
- Multiple apps need common types/utilities
- Want atomic commits across packages
- Tired of version hell with separate repos
- Need parallel builds with caching
Core Concepts
- Workspaces - pnpm manages multiple packages in one repo
- Turborepo - Orchestrates builds with caching and parallelization
- Shared types - Single source of truth for TypeScript types
- Build order - Dependencies build before dependents
Project Structure
project-root/
├── apps/
│ ├── web/ # Next.js frontend
│ │ ├── app/
│ │ ├── components/
│ │ └── package.json
│ ├── api/ # Backend API
│ │ ├── src/
│ │ └── package.json
│ └── worker/ # Background worker
│ ├── src/
│ └── package.json
│
├── packages/
│ ├── types/ # Shared TypeScript types
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ ├── user.ts
│ │ │ └── schemas.ts
│ │ └── package.json
│ ├── utils/ # Shared utilities
│ │ └── package.json
│ └── config/ # Shared configs (eslint, tsconfig)
│ └── package.json
│
├── package.json # Root package.json
├── pnpm-workspace.yaml
├── turbo.json
└── tsconfig.base.json
TypeScript Implementation
pnpm-workspace.yaml
packages:
- "apps/*"
- "packages/*"
Root package.json
{
"name": "my-saas",
"private": true,
"scripts": {
"dev": "turbo dev",
"build": "turbo build",
"test": "turbo test",
"lint": "turbo lint",
"typecheck": "turbo typecheck",
"clean": "turbo clean && rm -rf node_modules"
},
"devDependencies": {
"turbo": "^2.0.0",
"typescript": "^5.4.0"
},
"packageManager": "[email protected]"
}
turbo.json
{
"$schema": "https://turbo.build/schema.json",
"globalDependencies": ["**/.env.*local"],
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**"]
},
"dev": {
"cache": false,
"persistent": true
},
"test": {
"dependsOn": ["^build"]
},
"typecheck": {
"dependsOn": ["^build"]
},
"lint": {
"dependsOn": ["^build"]
},
"clean": {
"cache": false
}
}
}
tsconfig.base.json
{
"compilerOptions": {
"target": "ES2022",
"lib": ["ES2022"],
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"resolveJsonModule": true,
"isolatedModules": true
}
}
Shared Types Package
// packages/types/package.json
{
"name": "@myapp/types",
"version": "0.0.1",
"private": true,
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
}
},
"scripts": {
"build": "tsc",
"dev": "tsc --watch",
"typecheck": "tsc --noEmit"
},
"devDependencies": {
"typescript": "^5.4.0"
},
"dependencies": {
"zod": "^3.23.0"
}
}
// packages/types/tsconfig.json
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
// packages/types/src/index.ts
export * from './user';
export * from './schemas';
// packages/types/src/user.ts
export interface User {
id: string;
email: string;
name: string;
role: 'admin' | 'user' | 'guest';
createdAt: Date;
}
export interface CreateUserInput {
email: string;
name: string;
role?: 'admin' | 'user' | 'guest';
}
// packages/types/src/schemas.ts
import { z } from 'zod';
export const UserSchema = z.object({
id: z.string().uuid(),
email: z.string().email(),
name: z.string().min(1),
role: z.enum(['admin', 'user', 'guest']),
createdAt: z.coerce.date(),
});
export const CreateUserSchema = z.object({
email: z.string().email(),
name: z.string().min(1),
role: z.enum(['admin', 'user', 'guest']).default('user'),
});
App Package Using Shared Types
// apps/web/package.json
{
"name": "@myapp/web",
"version": "0.0.1",
"private": true,
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
},
"dependencies": {
"@myapp/types": "workspace:*",
"next": "^14.0.0",
"react": "^18.0.0"
}
}
// apps/web/app/api/users/route.ts
import type { User, CreateUserInput } from '@myapp/types';
import { CreateUserSchema } from '@myapp/types';
export async function POST(request: Request) {
const body = await request.json();
// Validate with shared schema
const input = CreateUserSchema.parse(body);
// Create user...
const user: User = await createUser(input);
return Response.json(user);
}
Shared Utils Package
// packages/utils/package.json
{
"name": "@myapp/utils",
"version": "0.0.1",
"private": true,
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"scripts": {
"build": "tsc",
"dev": "tsc --watch"
},
"devDependencies": {
"typescript": "^5.4.0"
}
}
// packages/utils/src/index.ts
export function formatDate(date: Date): string {
return date.toISOString().split('T')[0];
}
export function slugify(text: string): string {
return text
.toLowerCase()
.replace(/[^\w\s-]/g, '')
.replace(/\s+/g, '-');
}
export function sleep(ms: number): Promise<void> {
return new Promise(resolve => setTimeout(resolve, ms));
}
Common Commands
# Install all dependencies
pnpm install
# Run all dev servers in parallel
pnpm dev
# Build everything (respects dependency order)
pnpm build
# Run tests across all packages
pnpm test
# Add dependency to specific package
pnpm add zod --filter @myapp/types
# Add dev dependency to root
pnpm add -D prettier -w
# Run command in specific package
pnpm --filter @myapp/web dev
# Run command in all packages matching pattern
pnpm --filter "@myapp/*" build
Dependency Flow
packages/types (source of truth)
↓
packages/utils (may import types)
↓
apps/web, apps/api, apps/worker (import both)
Turborepo handles build order via dependsOn: ["^build"] - packages always build before apps that depend on them.
.gitignore
# Dependencies
node_modules/
# Build outputs
dist/
.next/
.turbo/
# Environment
.env
.env.local
.env.*.local
# IDE
.idea/
.vscode/
# OS
.DS_Store
Best Practices
- Use
workspace:*- Always for internal dependencies - Types flow down - Shared types package is the source of truth
- One tsconfig.base - Extend from root, override only what's needed
- Atomic commits - Change types and consumers in same commit
- Cache builds - Turborepo caches unchanged packages
Common Mistakes
- Using
^1.0.0instead ofworkspace:*for internal deps - Building packages individually instead of
turbo build - Circular dependencies between packages
- Not including
dist/in.gitignore - Forgetting
dependsOn: ["^build"]in turbo.json