Turborepo Introduction - Monorepo Management

What You’ll Learn in This Tutorial

✓ Turborepo setup
✓ Workspace configuration
✓ Pipeline settings
✓ Cache utilization
✓ Remote caching

Step 1: Create Project

npx create-turbo@latest my-monorepo
cd my-monorepo

Step 2: Directory Structure

my-monorepo/
├── apps/
│   ├── web/          # Next.js app
│   └── docs/         # Documentation site
├── packages/
│   ├── ui/           # Shared UI components
│   ├── config/       # Shared configuration
│   └── tsconfig/     # TypeScript config
├── turbo.json
└── package.json

Step 3: Root package.json

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  }
}

Step 4: turbo.json Configuration

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

Step 5: Shared Package

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "main": "./index.tsx",
  "types": "./index.tsx",
  "exports": {
    ".": "./index.tsx",
    "./button": "./button.tsx"
  }
}

// packages/ui/button.tsx
export function Button({ children, onClick }: {
  children: React.ReactNode;
  onClick?: () => void;
}) {
  return (
    <button onClick={onClick} className="btn">
      {children}
    </button>
  );
}

Step 6: Using in Apps

// apps/web/package.json
{
  "name": "web",
  "dependencies": {
    "@repo/ui": "workspace:*"
  }
}

// apps/web/app/page.tsx
import { Button } from '@repo/ui/button';

export default function Home() {
  return <Button>Click me</Button>;
}

Step 7: Running Commands

# Build all packages
turbo build

# Build specific package only
turbo build --filter=web

# Include dependencies
turbo build --filter=web...

# Development server
turbo dev

# Clear cache
turbo clean

Step 8: Remote Caching

# Vercel remote caching
npx turbo login
npx turbo link

# Configure with environment variables
TURBO_TEAM=your-team
TURBO_TOKEN=your-token

Best Practices

✓ Common dependencies at root
✓ Separate tsconfig per package
✓ Use workspace:* for internal packages
✓ Maximize cache utilization

Summary

Turborepo is a fast monorepo build tool. It significantly reduces build times through caching and parallel execution.