Turborepo 시작하기 - 모노레포 빌드 속도 10배 빠르게 만드는 법

Turborepo 시작하기 - 모노레포 빌드 속도 10배 빠르게 만드는 법

모노레포 프로젝트가 커질수록 빌드 시간이 늘어나는 건 개발자라면 누구나 겪는 문제예요. Turborepo는 Vercel에서 만든 고성능 빌드 시스템으로, 똑똑한 캐싱과 병렬 처리로 이 문제를 해결해줍니다.

Turborepo가 필요한 이유

일반적인 모노레포 도구들은 모든 패키지를 매번 처음부터 빌드하는데, Turborepo는 변경된 부분만 다시 빌드해요. 예를 들어 10개 패키지 중 1개만 수정했다면, 나머지 9개는 캐시에서 가져와 빌드 시간을 대폭 줄일 수 있죠.
특히 CI/CD 환경에서는 리모트 캐싱으로 팀원들이 빌드 결과를 공유할 수 있어서, 처음 실행하는 개발자도 이미 캐시된 결과를 활용할 수 있어요.

프로젝트 설정하기

새 프로젝트에 Turborepo를 도입하는 방법은 간단해요:

npx create-turbo@latest

기존 프로젝트라면 직접 설치할 수 있어요:

npm install turbo --save-dev

프로젝트 루트에 turbo.json 파일을 생성하고 파이프라인을 정의하세요:

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

이 설정은 build 태스크가 의존하는 패키지들을 먼저 빌드하고, dist 폴더의 결과물을 캐싱하라는 의미예요.

파이프라인 이해하기

pipeline은 Turborepo의 핵심이에요. 각 태스크가 어떤 순서로 실행되고, 무엇을 캐싱할지 정의하죠.

dependsOn: 태스크 간 의존성을 설정해요. ^build는 "현재 패키지를 빌드하기 전에 의존하는 모든 패키지를 먼저 빌드하라"는 뜻이에요.

outputs: 캐싱할 파일이나 폴더를 지정해요. 여기 명시된 파일들이 변경되지 않으면 다음 빌드 시 캐시를 재사용합니다.

inputs: 특정 파일만 감시하고 싶다면 사용해요. 예를 들어 ["src/**"]로 설정하면 src 폴더 내 파일 변경만 추적해요.

Turborepo는 태스크를 최대한 병렬로 실행하면서도, dependsOn으로 명시된 순서는 반드시 지켜요.

실전 활용 팁

package.json에서 실행하기:

{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev --parallel",
    "test": "turbo run test"
  }
}

리모트 캐싱 활성화: Vercel 계정으로 로그인하면 팀 전체가 캐시를 공유할 수 있어요.

npx turbo login
npx turbo link

이제 CI에서 빌드한 결과를 로컬에서도 활용할 수 있어요.

주의사항

Turborepo는 파일 해시를 기반으로 캐싱하기 때문에, 환경변수에 의존하는 빌드는 명시적으로 설정해야 해요. turbo.json의 env 또는 globalEnv 필드에 환경변수를 추가하지 않으면, 같은 코드여도 다른 결과가 나올 수 있어요.

결론

Turborepo는 복잡한 설정 없이도 모노레포의 빌드 시간을 획기적으로 줄여줘요. 파이프라인 설정만 제대로 하면 로컬과 CI 모두에서 빠른 빌드 경험을 얻을 수 있죠. 특히 팀 규모가 크거나 패키지 수가 많은 프로젝트라면, 리모트 캐싱으로 더 큰 효과를 볼 수 있어요.