monorepo-structure

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

1. Workspaces - pnpm manages multiple packages in one repo
2. Turborepo - Orchestrates builds with caching and parallelization
3. Shared types - Single source of truth for TypeScript types
4. 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": "pnpm@9.0.0"
}

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

1. Use workspace:* - Always for internal dependencies
2. Types flow down - Shared types package is the source of truth
3. One tsconfig.base - Extend from root, override only what's needed
4. Atomic commits - Change types and consumers in same commit
5. Cache builds - Turborepo caches unchanged packages

Common Mistakes

• Using ^1.0.0 instead of workspace:* 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

Related Skills

• TypeScript Strict
• Environment Config