Monorepo Setup with Turborepo

# Monorepo Setup with Turborepo

Build scalable monorepos for your Google Antigravity projects using Turborepo. This guide covers workspace configuration, shared packages, caching strategies, and CI optimization.

## Project Structure

Organize your monorepo effectively:

```
my-monorepo/
├── apps/
│   ├── web/                 # Next.js web app
│   │   ├── package.json
│   │   └── ...
│   ├── docs/                # Documentation site
│   │   ├── package.json
│   │   └── ...
│   └── admin/               # Admin dashboard
│       ├── package.json
│       └── ...
├── packages/
│   ├── ui/                  # Shared UI components
│   │   ├── package.json
│   │   └── ...
│   ├── config/              # Shared configs
│   │   ├── eslint/
│   │   ├── typescript/
│   │   └── tailwind/
│   ├── database/            # Database client & types
│   │   ├── package.json
│   │   └── ...
│   └── utils/               # Shared utilities
│       ├── package.json
│       └── ...
├── turbo.json
├── package.json
└── pnpm-workspace.yaml
```

## Root Configuration

Configure the monorepo root:

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

```json
// package.json
{
  "name": "antigravity-monorepo",
  "private": true,
  "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.0.0",
    "turbo": "^2.0.0"
  },
  "packageManager": "pnpm@8.0.0",
  "engines": {
    "node": ">=18"
  }
}
```

## Turborepo Configuration

Configure task pipelines:

```json
// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "env": [
        "NEXT_PUBLIC_SUPABASE_URL",
        "NEXT_PUBLIC_SUPABASE_ANON_KEY"
      ]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "clean": {
      "cache": false
    }
  }
}
```

## Shared UI Package

Create reusable UI components:

```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"
  },
  "devDependencies": {
    "@repo/config-typescript": "workspace:*",
    "@types/react": "^18.2.0",
    "react": "^18.2.0",
    "typescript": "^5.0.0"
  },
  "peerDependencies": {
    "react": "^18.2.0"
  }
}
```

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

export interface ButtonProps extends 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-900 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": size === "md",
            "px-6 py-3 text-lg": size === "lg",
          },
          className
        )}
        {...props}
      />
    );
  }
);

Button.displayName = "Button";
```

## App Configuration

Configure apps to use shared packages:

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

## Remote Caching

Enable remote caching for CI:

```bash
# Enable remote caching
npx turbo login
npx turbo link

# Or use Vercel Remote Cache
export TURBO_TEAM="your-team"
export TURBO_TOKEN="your-token"
```

## GitHub Actions CI

Optimize CI with caching:

```yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"
      
      - run: pnpm install --frozen-lockfile
      
      - name: Build
        run: pnpm build
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
      
      - name: Lint
        run: pnpm lint
      
      - name: Test
        run: pnpm test
```

## Best Practices

1. **Workspace Protocol**: Use workspace:* for internal dependencies
2. **Shared Configs**: Centralize ESLint, TypeScript, and Tailwind configs
3. **Remote Caching**: Enable remote caching for faster CI builds
4. **Task Dependencies**: Define proper task dependencies in turbo.json
5. **Consistent Versioning**: Use same versions across packages
6. **Selective Builds**: Use --filter flag for targeted builds