Set Up a Monorepo with Turborepo

# pnpm-workspace.yaml — Declare workspace package locations.
# pnpm resolves workspace:* dependencies automatically.

packages:
  - "apps/*"
  - "packages/*"

monorepo/
├── apps/
│   ├── web/              # Customer dashboard (Next.js)
│   ├── admin/            # Admin panel (Vite + React)
│   └── marketing/        # Marketing site (Astro)
├── packages/
│   ├── ui/               # Shared React component library
│   ├── db/               # Prisma schema and client
│   ├── auth/             # Authentication utilities
│   ├── tsconfig/         # Shared TypeScript configs
│   └── eslint-config/    # Shared ESLint presets
├── turbo.json
├── pnpm-workspace.yaml
└── package.json

// turbo.json — Pipeline definition.
// The ^ prefix in dependsOn means "run this task in dependency packages first".
// So building @app/web first builds @repo/ui and @repo/db that it imports.
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV", "CI"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "build/**"],
      "env": ["NEXT_PUBLIC_*", "VITE_*"]
    },
    "dev": {
      "dependsOn": ["^build"],
      "persistent": true,
      "cache": false
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "env": ["DATABASE_URL"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "db:generate": {
      "cache": false
    },
    "db:migrate": {
      "cache": false
    }
  }
}

// packages/ui/package.json — Shared component library.
// "exports" field tells Node and bundlers exactly where to find each format.
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./styles.css": "./dist/style.css"
  },
  "scripts": {
    "build": "vite build && tsc --emitDeclarationOnly",
    "dev": "vite build --watch",
    "lint": "eslint src/",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@repo/eslint-config": "workspace:*",
    "@repo/tsconfig": "workspace:*",
    "vite": "^6.0.0",
    "react": "^19.0.0"
  },
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0"
  }
}

// packages/ui/src/components/Button.tsx — Example shared component.
// Exported from the package index, consumed by both apps.

import { type ButtonHTMLAttributes, forwardRef } from "react";
import { cva, type VariantProps } from "class-variance-authority";

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        primary: "bg-blue-600 text-white hover:bg-blue-700",
        secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
        destructive: "bg-red-600 text-white hover:bg-red-700",
        ghost: "hover:bg-gray-100",
      },
      size: {
        sm: "h-8 px-3 text-sm",
        md: "h-10 px-4 text-sm",
        lg: "h-12 px-6 text-base",
      },
    },
    defaultVariants: { variant: "primary", size: "md" },
  }
);

interface ButtonProps
  extends ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  isLoading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, isLoading, children, ...props }, ref) => (
    <button
      ref={ref}
      className={buttonVariants({ variant, size, className })}
      disabled={isLoading || props.disabled}
      {...props}
    >
      {isLoading ? <Spinner className="mr-2 h-4 w-4" /> : null}
      {children}
    </button>
  )
);
Button.displayName = "Button";

// packages/db/src/index.ts — Prisma client singleton.
// Re-exports the generated client so consumers import from @repo/db,
// not directly from @prisma/client (which would create multiple instances).

import { PrismaClient } from "@prisma/client";

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

// Reuse client in development to avoid exhausting database connections
// during Next.js hot reloads (each reload creates a new module scope)
export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === "development"
      ? ["query", "error", "warn"]
      : ["error"],
  });

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

// Re-export types so consumers don't need @prisma/client as a dependency
export type { User, Post, Comment, Team } from "@prisma/client";
export { Prisma } from "@prisma/client";

# .github/workflows/ci.yml — Monorepo CI with Turborepo caching.
# turbo prune creates a minimal workspace for Docker builds.

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

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # Need parent commit for change detection

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - run: pnpm install --frozen-lockfile

      # Run all checks in parallel — Turborepo handles the dependency graph
      - name: Lint, typecheck, test, build
        run: pnpm turbo run lint typecheck test build

      # Print cache hit summary for debugging slow CI
      - name: Build summary
        run: pnpm turbo run build --summarize | tail -20

  # Deploy only changed apps
  deploy-web:
    needs: check
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - run: pnpm install --frozen-lockfile

      # turbo prune generates a minimal package.json + lockfile
      # for just @app/web and its workspace dependencies
      - name: Prune for web app
        run: pnpm turbo prune @app/web --docker

      # The pruned output is a minimal workspace — perfect for Docker COPY
      - name: Build Docker image
        run: |
          docker build -f apps/web/Dockerfile \
            --build-arg TURBO_TOKEN=$TURBO_TOKEN \
            --build-arg TURBO_TEAM=$TURBO_TEAM \
            -t web:${{ github.sha }} \
            out/

# apps/web/Dockerfile — Multi-stage build using pruned monorepo.
# Stage 1 installs deps from the pruned lockfile (only @app/web's deps).
# Stage 2 builds with Turborepo cache. Stage 3 is the minimal runtime.

FROM node:20-alpine AS deps
RUN corepack enable
WORKDIR /app
COPY pruned/json/ .
COPY pruned/pnpm-lock.yaml .
RUN pnpm install --frozen-lockfile

FROM node:20-alpine AS builder
RUN corepack enable
WORKDIR /app
COPY --from=deps /app/ .
COPY pruned/full/ .
ARG TURBO_TOKEN
ARG TURBO_TEAM
RUN pnpm turbo run build --filter=@app/web

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/apps/web/.next/standalone ./
COPY --from=builder /app/apps/web/.next/static ./apps/web/.next/static
COPY --from=builder /app/apps/web/public ./apps/web/public
EXPOSE 3000
CMD ["node", "apps/web/server.js"]