Turborepo 적용 - maeng2418/zzik-meok GitHub Wiki

목차

  1. Turborepo란?
  2. Turborepo의 주요 장점
  3. 핵심 설정 요소
  4. 현재 프로젝트 설정 분석
  5. 실전 사용 예시

Turborepo란?

Turborepo는 JavaScript/TypeScript 모노레포를 위한 고성능 빌드 시스템입니다. 주요 특징으로는:

  • 지능적인 태스크 스케줄링
  • 증분 빌드
  • 원격/로컬 캐싱
  • 병렬 실행
  • 의존성 관리

Turborepo의 주요 장점

1. 스마트한 빌드 시스템

  • 변경된 파일만 선택적으로 빌드
  • 의존성 그래프 기반 실행 순서 최적화
  • 병렬 처리를 통한 성능 향상

2. 강력한 캐싱 메커니즘

  • 로컬 캐시를 통한 빌드 결과 재사용
  • 원격 캐시 공유로 팀 협업 최적화
  • 정확한 캐시 무효화 전략

3. 효율적인 의존성 관리

  • 패키지 간 의존성 자동 분석
  • 순환 의존성 감지
  • 최적의 빌드 순서 결정

핵심 설정 요소

1. globalDependencies

모든 태스크에 영향을 미치는 전역 의존성 파일을 정의합니다.

{
  "globalDependencies": [".env*", "tsconfig.json"]
}

효과:

  • 전역 설정 파일 변경 시 전체 캐시 무효화
  • 프로젝트 전반의 일관성 유지

예시 시나리오:

// tsconfig.json 수정 시
1. 모든 빌드 캐시 무효화
2. 전체 패키지 재빌드
3. 새로운 TypeScript 설정 적용

2. globalEnv

캐시 키에 포함될 환경 변수를 지정합니다.

{
  "globalEnv": [
    "NODE_ENV",
    "NEXT_PUBLIC_*",
    "VERCEL_*",
    "DATABASE_URL"
  ]
}

효과:

  • 환경별 독립적인 캐시 관리
  • 환경 변수 변경 시 관련 캐시만 무효화

예시:

# 개발 환경
NODE_ENV=development
→ 개발용 캐시 사용

# 프로덕션 환경
NODE_ENV=production
→ 프로덕션용 캐시 사용

3. tasks

실행 가능한 작업 단위들을 정의합니다.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**/*.test.ts"]
    }
  }
}

주요 태스크 설정:

  1. build: 패키지 빌드
  2. dev: 개발 서버
  3. test: 테스트 실행
  4. lint: 코드 검사

4. dependsOn

태스크 간의 의존성을 정의합니다.

{
  "build": {
    "dependsOn": ["^build"]
  }
}

특수 기호:

  • ^: 워크스페이스 의존성 (package.json의 dependencies)
  • $: 같은 워크스페이스 내 태스크

예시 시나리오:

// 프로젝트 구조
packages/
  ├─ ui/
  └─ web/     // ui 패키지에 의존
      
// 빌드 순서
1. ui 패키지 빌드
2. web 패키지 빌드

5. inputs/outputs

캐시 및 빌드 관련 파일을 정의합니다.

{
  "build": {
    "inputs": ["src/**/*.tsx", "package.json"],
    "outputs": ["dist/**", ".next/**"]
  }
}

inputs:

  • 캐시 무효화 조건 파일들
  • 변경 감지 대상
  • 빌드 트리거 조건

outputs:

  • 빌드 결과물 위치
  • 캐시할 파일들
  • 재사용할 결과물

예시:

// src/Button.tsx 수정 시
1. inputs 패턴 매칭 확인
2. 캐시 무효화
3. 새로운 빌드 실행
4. dist/ 결과물 생성 및 캐시

6. cache와 persistent

{
  "build": {
    "cache": true
  },
  "dev": {
    "persistent": true
  }
}

cache:

  • true: 결과물 캐싱 활성화
  • false: 매번 새로 실행

persistent:

  • true: 계속 실행 (watch 모드)
  • false: 실행 후 종료

현재 프로젝트 설정 분석

1. 전역 설정

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env*", "tsconfig.json"],
  "globalEnv": ["NODE_ENV", "NEXT_PUBLIC_*", "VERCEL_*", "DATABASE_URL"]
}

특징:

  • 환경 설정 파일 변경 감지
  • 주요 환경 변수 관리
  • 배포 환경 설정 통합

2. 빌드 설정

{
  "build": {
    "dependsOn": ["^build"],
    "outputs": [
      "dist/**",
      ".next/**",
      "!.next/cache/**",
      "build/**",
      "public/build/**"
    ],
    "cache": true
  }
}

특징:

  • 의존성 기반 빌드 순서
  • Next.js 최적화
  • 효율적인 캐시 관리

3. 개발 설정

{
  "dev": {
    "cache": false,
    "persistent": true,
    "dependsOn": ["^build"]
  }
}

특징:

  • 실시간 개발 환경
  • 의존성 패키지 자동 빌드
  • 캐시 없는 즉시 반영

실전 사용 예시

1. 기본 명령어

# 전체 빌드
turbo run build

# 특정 패키지만 빌드
turbo run build --filter=@zzik-meok/ui

# 테스트 실행
turbo run test

# 개발 서버 시작
turbo run dev

2. 고급 사용법

# 변경된 패키지만 빌드
turbo run build --filter=[HEAD^1]

# 캐시 비활성화 빌드
turbo run build --no-cache

# 병렬 테스트 실행
turbo run test --parallel

# 원격 캐시 사용
turbo run build --team="my-team" --token="my-token"

3. 의존성 필터링

# 특정 패키지와 의존성 포함 빌드
turbo run build --filter=@zzik-meok/web...

# 특정 패키지 제외 빌드
turbo run build --filter=!@zzik-meok/ui

# 의존성 역방향 빌드
turbo run build --filter=...@zzik-meok/web

결론

Turborepo의 설정을 통해:

  1. 빌드 성능 최적화

    • 캐시 활용
    • 병렬 처리
    • 증분 빌드

  2. 개발 생산성 향상

    • 자동화된 의존성 관리
    • 스마트한 태스크 실행
    • 효율적인 캐시 전략

  3. 팀 협업 개선

    • 원격 캐시 공유
    • 일관된 빌드 환경
    • 명확한 의존성 구조

이를 통해 대규모 모노레포 프로젝트에서 아래와 같이 달성할 수 있습니다.

  • 빌드 시간 단축
  • 리소스 사용 최적화
  • 개발 경험 향상
  • 팀 생산성 증대