giuseppe-trisciuoglio/turborepo-monorepo

turborepo-monorepo은(는) 무엇을 하나요?

TypeScript/JavaScript 프로젝트를 위한 포괄적인 Turborepo 모노레포 관리 가이드를 제공합니다. Turborepo 워크스페이스 생성, turbo.json 태스크 구성, Next.js/NestJS 앱 설정, 테스트 파이프라인(Vitest/Jest) 관리, CI/CD 구성, 원격 캐싱 구현, 모노레포 빌드 성능 최적화에 사용하세요.

주요 기능

• 워크스페이스 관리: pnpm-workspace.yaml 또는 npm workspaces를 사용한 패키지 구성
• 태스크 파이프라인: turbo.json에서 dependsOn, cache, outputs 설정
• 프레임워크 통합: Next.js, NestJS, Vite 등의 앱 추가 및 구성
• 테스트 파이프라인: Vitest, Jest를 사용한 테스트 설정 및 실행
• CI/CD 통합: GitHub Actions, GitLab CI 등에서 Turborepo 활용
• 원격 캐싱: Vercel Remote Caching 또는 자체 호스팅 캐시 서버 설정
• 빌드 최적화: 병렬 실행, 캐싱 전략, 의존성 그래프 최적화

사용 방법

1. 워크스페이스 생성: pnpm init 및 루트 pnpm-workspace.yaml 파일 설정
2. Turborepo 구성: npx create-turbo@latest 또는 수동으로 turbo.json 작성
3. 앱 및 패키지 추가: apps/와 packages/ 디렉토리 구조 활용
4. 태스크 정의: turbo.json에서 build, test, lint, dev 등의 파이프라인 정의
5. 원격 캐싱: Vercel 계정 연결 또는 TURBO_API, TURBO_TOKEN, TURBO_TEAM 환경 변수 설정

예시 turbo.json

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

CI/CD 예시 (GitHub Actions)

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm build
      - run: pnpm test

환경 변수

• TURBO_TOKEN: Vercel 원격 캐싱 인증 토큰
• TURBO_TEAM: Vercel 팀 ID
• TURBO_API: 자체 호스팅 캐시 서버 URL
• TURBO_REMOTE_ONLY: 원격 캐시만 사용 (로컬 캐시 무시)

권장 사항

• 모든 패키지에 동일한 Node.js 버전 사용
• pnpm을 패키지 매니저로 권장 (엄격한 의존성 관리)
• turbo.json에서 outputs를 명시적으로 정의하여 캐시 효율성 향상
• CI 환경에서 원격 캐싱을 활성화하여 빌드 시간 단축