터보레포 (Turborepo)

HG 프로젝트 중 선배님이 올리신 PR이 터보레포 관련인 것을 보고 터보레포가 궁금해 무엇인지 찾아보게 되었다.

터보레포 (Turborepo) 란?

터보레포는 모노레포 환경에서 빌드와 작업을 효율적으로 하기 위한 빌드 도구이다.

모노레포는 한 레포지토리에서 여러 애플리케이션과 하나의 패키지가 존재하기 때문에 프로젝트가 커지면 다음과 같은 문제가 일어 날 수 있다.

• 전체 프로젝트를 다시 빌드해야 하는 문제
• 빌드 시간이 점점 길어지는 문제
• 변경된 패키지와 관계없는 작업까지 실행되는 문제

터보레포는 이러한 문제들을 dependency graph, task pipeline, cache를 활용하여 개선한다.

터보레포 핵심 개념

1. dependency graph

dependency graph는 패키지 간 의존 관계를 그래프로 표현한 것이다.

예를 들어 다음과 같은 모노레포 구조가 있다고 가정해보자.

apps
├ client
└ admin

packages
├ ui
└ utils

패키지 간 의존 관계가 다음과 같다면,

client → ui
admin → ui
client → utils

이 관계를 dependency graph로 표현 할 수 있다.

터보레포는 dependency graph를 통해 변경된 패키지와 영향을 받는 패키지를 계산한다.

예를들어 utils가 수정된다면 수정된 파일인 utils 와 utils를 사용하는 client만 실행되고 utils를 사용하지 않는 admin은 실행되지 않는다.

2. Task Pipeline

Turborepo는 작업(task)을 pipeline 형태로 관리한다.

task는 보통 package.json의 script에 정의된 작업을 의미한다.

하지만 터보레포에서는 turbo.json 파일을 통해 task의 실행 규칙을 정의할 수 있다.

예를들어 지금 사용중인 프로젝트에서는 다음과 같이 설정되어 있다.

{
  "$schema": "https://turborepo.dev/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

이 설정을 통해 터보레포는 의존성을 확인하고 실행방식을 파악하여 Pipeline을 구축한다.

---

dependsOn을 통한 작업 순서 관리

이 전 코드를 보면 build 안에 dependsOn": ["^build"] 라는 코드를 확인 할 수 있다.
이 설정의 의미는 build시 의존하는 패키지부터 build 하라는 의미이다.

client → ui
admin → ui
client → utils

위와 같은 의존성이 있을 때

ui build → client build → admin build 순으로 진행된다.

Turborepo는 task pipeline에 정의된 실행 규칙과 dependency graph를 기반으로 작업 실행 순서를 자동으로 결정한다.

---

병렬 실행을 통한 성능 최적화

ui와 utils 처럼 서로 의존하지 않는 작업은 병렬로 실행된다.

병렬로 실행됨으로 써 불필요한 시간을 줄이고 빌드 시간을 최적화 할 수 있다.

3. Cache

Turborepo는 작업 결과를 cache로 저장한다.

만약 이전에 동일한 작업이 실행되었고 코드에 변경이 없다면
다음 실행에서는 해당 작업을 다시 실행하지 않고 cache를 재사용한다.

예를 들어 이미 빌드가 완료된 상태에서 다시 빌드를 실행하면

build → cache hit

이 되어 실제 빌드가 실행되지 않는다.

4. Remote Cache

Turborepo는 Remote Cache 기능을 통해 팀원들과 캐시를 공유할 수도 있다.

예를 들어 개발자 A가 이미 빌드를 수행했다면
그 결과를 remote cache에 저장할 수 있고,

다른 개발자 B는 동일한 작업을 실행할 때
해당 캐시를 다운로드하여 빌드를 다시 수행하지 않아도 된다.

이를 통해 팀 전체의 빌드 시간을 크게 줄일 수 있다.

터보레포 동작과정

Turborepo는 작업을 실행할 때 여러 파일의 정보를 참고하여 어떤 작업을 실행할지 결정한다.

1. 패키지 구조 파악

먼저 Turborepo는 워크스페이스 설정 파일을 참고하여 모노레포의 패키지 구조를 파악한다.

예를 들어 프로젝트 루트에 있는 pnpm-workspace.yaml 파일을 통해 어떤 폴더가 workspace에 포함되는지 확인한다.

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

이 설정을 통해 Turborepo는 구조를 확인한다.

2. 패키지 의존 관계 분석

다음으로 각 패키지들의 의존성을 package.json에서 확인한다.

패키지들의 의존성을 확인 한 후 dependency graph를 생성한다.

3. turbo.json을 통해 task 실행 규칙 확인

그 다음 터보레포는 루트의 turbo.json파일을 참고하여 task 실행 규칙을 확인한다.

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

"dependsOn": ["^build"] 설정은 현재 패키지가 의존하는 패키지의 build작업을 먼저 실행하라는 의미이다.

4. 변경된 패키지 확인

그 다음 Turborepo는 변경된 파일을 기반으로 어떤 패키지가 영향을 받는지 판단한다.

수정 된 패키지를 확인하고, 변경된 파일 기반으로 영향을 받는 패키지만 재 실행 시킨다.

5. 작업 실행 및 캐시 확인

마지막으로 Turborepo는 실행할 작업을 결정하고 캐시를 확인한다.

이미 동일한 작업이 실행된 적이 있다면 cache hit가 발생하고 작업을 다시 실행하지 않는다.

ui build
utils build
client build

이 과정에서 의존 관계가 없는 작업은 병렬로 실행되어 빌드 시간을 단축한다.

결론

Turborepo는 단순히 모노레포를 구성하는 도구가 아니라
모노레포 환경에서 빌드와 작업을 최적화하는 빌드 시스템이다.

dependency graph와 task pipeline을 기반으로
필요한 작업만 실행하고 캐시를 활용하여 빌드 시간을 줄여준다.

프로젝트 규모가 커질수록 이러한 빌드 최적화는 더욱 중요해지기 때문에
모노레포를 사용하는 프로젝트에서는 Turborepo와 같은 도구가 큰 도움이 된다.