monorepo

Monorepo Skill

Turborepo + pnpm workspaces for managing multi-app, multi-package repositories efficiently.

1. Repository Structure

monorepo/
├── apps/
│   ├── web/               # Next.js app
│   ├── api/               # FastAPI or Express backend
│   └── docs/              # Docusaurus or similar
├── packages/
│   ├── ui/                # Shared React component library
│   ├── config/            # Shared ESLint, TypeScript, Tailwind configs
│   ├── types/             # Shared TypeScript types / Zod schemas
│   └── utils/             # Shared utility functions
├── turbo.json
├── pnpm-workspace.yaml
└── package.json           # Root — scripts only, no app deps

2. pnpm Workspaces

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

// Root package.json
{
  "name": "my-monorepo",
  "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"
  },
  "engines": { "node": ">=20", "pnpm": ">=9" }
}

workspace: Protocol — Cross-Package Dependencies

// apps/web/package.json
{
  "dependencies": {
    "@myapp/ui": "workspace:*",      // Always latest local version
    "@myapp/types": "workspace:^",   // Semver compatible local version
    "@myapp/utils": "workspace:*"
  }
}

Rules:

• workspace:* — consume local package always (recommended for internal packages)
• workspace:^ — enforces semver compatibility (use for packages that may be published)
• Never use relative paths ("../packages/ui") — use workspace protocol

3. Turborepo Configuration

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],         // Build dependencies first (topological)
      "inputs": ["src/**", "package.json"],
      "outputs": [".next/**", "dist/**", "!.next/cache/**"]
    },
    "dev": {
      "persistent": true,              // Keep running (dev servers)
      "cache": false,                  // Never cache watch mode
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "test/**", "vitest.config.ts"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "inputs": ["src/**", ".eslintrc*", "eslint.config.*"]
    },
    "typecheck": {
      "dependsOn": ["^build"],         // Types may be generated by build
      "inputs": ["src/**", "tsconfig*.json"]
    },
    "clean": {
      "cache": false
    }
  }
}