Turborepo Monorepo Setup Complete Guide

# Turborepo Monorepo Setup Guide

Create scalable monorepo architectures with Turborepo for managing multiple applications and shared packages efficiently.

## Project Structure

### Directory Layout

```
my-turborepo/
├── apps/
│   ├── web/                 # Next.js app
│   │   ├── package.json
│   │   └── next.config.js
│   ├── admin/               # Admin dashboard
│   │   └── package.json
│   └── api/                 # Express API
│       └── package.json
├── packages/
│   ├── ui/                  # Shared UI components
│   │   ├── package.json
│   │   └── src/
│   ├── config-eslint/       # Shared ESLint config
│   ├── config-typescript/   # Shared TS config
│   └── database/            # Prisma client
│       ├── package.json
│       └── prisma/
├── turbo.json
├── package.json
└── pnpm-workspace.yaml
```

### Root Configuration

```json
// package.json
{
  "name": "my-turborepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "test": "turbo test",
    "clean": "turbo clean && rm -rf node_modules",
    "format": "prettier --write \"**/*.{ts,tsx,md}\""
  },
  "devDependencies": {
    "prettier": "^3.2.0",
    "turbo": "^2.0.0"
  },
  "packageManager": "pnpm@8.15.0"
}
```

```yaml
# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"
```

## Turbo Configuration

### Pipeline Setup

```json
// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV", "CI"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "env": ["NEXT_PUBLIC_*", "DATABASE_URL"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "env": ["CI", "DATABASE_URL"]
    },
    "clean": {
      "cache": false
    },
    "db:generate": {
      "cache": false
    },
    "db:push": {
      "cache": false
    }
  }
}
```

## Shared UI Package

```json
// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    "./button": "./src/button.tsx",
    "./card": "./src/card.tsx",
    "./input": "./src/input.tsx",
    "./*": "./src/*.tsx"
  },
  "scripts": {
    "lint": "eslint . --ext .ts,.tsx",
    "build": "tsc"
  },
  "devDependencies": {
    "@repo/config-typescript": "workspace:*",
    "typescript": "^5.3.0"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  }
}
```

```typescript
// packages/ui/src/button.tsx
import { forwardRef } from "react";
import { cn } from "./utils";

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "outline";
  size?: "sm" | "md" | "lg";
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant = "primary", size = "md", ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={cn(
          "rounded-lg font-medium transition-colors",
          {
            "bg-blue-600 text-white hover:bg-blue-700": variant === "primary",
            "bg-gray-200 text-gray-800 hover:bg-gray-300": variant === "secondary",
            "border border-gray-300 hover:bg-gray-50": variant === "outline",
          },
          {
            "px-3 py-1.5 text-sm": size === "sm",
            "px-4 py-2 text-base": size === "md",
            "px-6 py-3 text-lg": size === "lg",
          },
          className
        )}
        {...props}
      />
    );
  }
);
Button.displayName = "Button";
```

## Database Package

```json
// packages/database/package.json
{
  "name": "@repo/database",
  "version": "0.0.0",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "scripts": {
    "db:generate": "prisma generate",
    "db:push": "prisma db push",
    "db:migrate": "prisma migrate dev",
    "db:studio": "prisma studio"
  },
  "dependencies": {
    "@prisma/client": "^5.10.0"
  },
  "devDependencies": {
    "prisma": "^5.10.0"
  }
}
```

```typescript
// packages/database/src/index.ts
import { PrismaClient } from "@prisma/client";

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };

export const prisma = globalForPrisma.prisma || new PrismaClient();

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

export * from "@prisma/client";
```

## App Configuration

```json
// apps/web/package.json
{
  "name": "@repo/web",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "dev": "next dev --port 3000",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "@repo/ui": "workspace:*",
    "@repo/database": "workspace:*",
    "next": "^14.1.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@repo/config-typescript": "workspace:*",
    "@repo/config-eslint": "workspace:*"
  }
}
```

```typescript
// apps/web/app/page.tsx
import { Button } from "@repo/ui/button";
import { prisma } from "@repo/database";

export default async function Home() {
  const users = await prisma.user.findMany({ take: 10 });

  return (
    <main>
      <h1>Welcome to Turborepo</h1>
      <Button variant="primary">Click me</Button>
      <ul>
        {users.map((user) => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </main>
  );
}
```

## Remote Caching

```bash
# Login to Vercel for remote caching
npx turbo login

# Link to your Vercel team
npx turbo link

# Enable remote caching in CI
TURBO_TOKEN=${{ secrets.TURBO_TOKEN }}
TURBO_TEAM=${{ secrets.TURBO_TEAM }}
```

## Task Filtering

```bash
# Run dev for specific app
pnpm turbo dev --filter=@repo/web

# Build with dependencies
pnpm turbo build --filter=@repo/web...

# Run tests in changed packages
pnpm turbo test --filter=[HEAD^1]

# Build everything except docs
pnpm turbo build --filter=!@repo/docs
```

This Turborepo guide provides scalable monorepo architecture with shared packages, pipelines, and remote caching.