Turborepo와 PNPM으로 Monorepo 시작하기

📒 Turborepo와 PNPM으로 Monorepo 시작하기

---

요즘엔 모놀리식 혹은 멀티레포 구조보다 중복 코드와 의존성 관리 측면에서 유리한 모노레포 구조가 많이 사용됩니다.

모노레포 구조를 구축하는 방법엔 여러 가지가 있지만 저는 Turborepo로 손쉽게 환경을 구축하는 방법을 소개합니다.

 

📌 Turborepo란?

Turborepo는 Vercel에서 개발한 JS/TS 모노레포 빌드 시스템입니다.

기존 모노레포 관리 도구인 Lerna나 Nx와 유사하지만, 더 빠르고 효율적인 빌드 성능을 제공합니다.

 

주요 장점은 다음과 같습니다.

• 캐싱 및 병렬 실행
  • 같은 작업을 여러 번 실행하지 않고 결과를 캐싱하여 불필요한 중복 빌드를 방지
  • 여러 패키지의 빌드를 병렬로 실행하여 속도 최적화
• 효율적인 의존성 분석
  • 각 패키지의 의존성을 분석하여, 변경된 부분만 다시 빌드해요.
  • turbo run build 같은 명령어를 실행하면 변경된 패키지만 다시 처리해서 빌드 시간을 단축할 수 있어요.
• 원격 캐싱
  • Vercel과 통합하여 팀원들끼리 캐시를 공유
  • 로컬에서 빌드했던 결과를 다른 팀원이 다시 실행할 때도 재사용

 

저도 지금은 계속해서 학습하는 중이지만 설정이 직관적이라 러닝커브가 높지 않다는 것도 큰 장점이라 생각됩니다.

 

📌 Turborepo + pnpm 모노레포 프로젝트 생성

Installation | Turborepo

$ npx create-turbo@latest

위 명령어를 통해 설치하면 폴더명과 패키지 매니저를 선택하고, 기본적인 monorepo 템플릿과 함께 프로젝트가 생성됩니다.

저는 패키지 매니저로 pnpm을 선택했으며, pnpm workspace로 생성된 프로젝트는 다음과 같은 폴더구조를 갖습니다.

 

다양한 프레임워크에 기반한 예제들을 확인하고 싶으시면 위 공식문서를 참고해 주세요.

그럼 monorepo를 구성하는 주요 파일들에 대해 설명드립니다.

 

📌 pnpm-workspace.yaml

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

pnpm-workspace.yaml은 pnpm에서 모노레포를 관리할 때 사용하는 워크스페이스 설정 파일입니다.

 

packages 키워드로 모노레포 내에서 관리할 패키지들의 경로를 지정할 수 있으며, 위에서 생성한 프로젝트의 경우 apps/*, packages/* 폴더를 관리할 패키지로 등록합니다.

이렇게 등록한 패키지들은 서로 각 폴더 내 package.json의 dependencies로 추가해 링크할 수 있으며, install시 각 패키지의 최신 버전이 자동으로 반영되어 중복된 코드를 손쉽게 관리할 수 있습니다.

"dependencies": {
  "@repo/ui": "workspace:*",
  ...
},

위 프로젝트에서 packages/ui 패키지를 apps/web에서 사용하기 위해선, 위와 같이 사용할 패키지 이름과 모노레포에서 사용되는 버전  ["@repo/ui: "workspace:*"]을 지정해 주면 항상 로컬의 최신 버전을 참조할 수 있게 됩니다.

 

"workspace:"는 pnpm, Yarn, npm에서 제공하는 워크스페이스 기능 중 하나로, 모노레포 내에서 특정 패키지를 참조할 때 사용하는 버전 지정 방법입니다.

 

 

이러한 공통 컴포넌트뿐만 아니라 eslint, tsconfig, prettier 설정들도 하나로 모아서 관리할 수 있어 여러 프로젝트를 관리하기 용이합니다.

 

📌 turbo.json

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

turbo.json은 Turborepo에서 빌드, 테스트, 배포 등의 작업을 구성하는 핵심 설정 파일입니다.

이 파일을 사용하면 모노레포 내에서 각 패키지의 작업 실행 순서, 캐싱, 병렬 실행 등을 효율적으로 관리할 수 있습니다.

 

여러 속성들이 있지만 주요한 키워드들만 설명드리겠습니다.

 

🔎 tasks

{
  "tasks": {
    "build": {
      ...
    },
    "lint": {
      ...
    },
  }
}

tasks는 turbo.json에서 각 작업의 실행 방식, 실행 순서, 캐싱, 입출력 파일 등을 정의하는 부분입니다.

이 속성 안에 있는 내부 속성들의 key 값들은 실행 가능한 작업으로 등록되고, $ turbo run <task-key>로 실행할 수 있습니다.

 $ turbo run <task-key>가 실행되었다면 등록된 workspace 패키지들의 package.json에 해당하는 task-key 명령어가 실행됩니다.

예를 들어 turbo run build를 실행했다면 모든 패키지의 build 명령어가 실행됩니다.

 

🔎 dependsOn

"dependsOn": ["^build"]

dependsOn은 작업 간의 의존 관계를 설정하는 속성입니다.

즉, 특정 작업을 실행하기 전에 다른 작업이 먼저 실행되도록 지정할 수 있어, 이를 통해 작업 실행 순서를 명시적으로 조정할 수 있습니다.

 

예를 들어 아래와 같이 설정해 두었다고 가정하겠습니다.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "test": {
      "dependsOn": ["build", "lint"]
    }
  }
}

• "build": { "dependsOn": ["^build"] }
  • ^build는 현재 작업뿐만 아니라, 의존하는 모든 패키지에서 build 작업을 먼저 실행하도록 설정하는 것입니다.
  • build 작업이 실행되기 전에, 모든 의존성 패키지들의 build 작업이 먼저 완료됩니다.
  • 예를 들어, ui 패키지가 web을 의존하고 있으면, web의 build 작업은 ui가 먼저 빌드된 후 실행됩니다.
• "test": { "dependsOn": ["build", "lint"] }
  • test 작업을 실행하기 전에 build와 lint 작업이 먼저 완료되도록 합니다.
  • 따라서, test는 build와 lint가 모두 끝난 후에 실행됩니다.

 

🔎 캐싱

turborepo의 강력한 기능 중 하나인 캐싱은 여러 속성에 의해 영향받기 때문에 한 번에 묶어서 설명드리겠습니다.

{
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

• cache
  • 캐싱 활성화 여부
  • false면 매번 새로 실행
• presistent
  • 지속 실행 여부
  • true면 실행 후 종료되지 않고 계속 실행
  • watch mode가 필요한 경우 사용
• inputs
  • 캐싱을 무효화할 파일 지정
• outputs
  • 특정 폴더를 빌드 결과물로 지정해서 변화 유무에 따라 캐싱

---

그럼 터보레포를 이용해 모노레포를 구축하는 방법은 여기서 마무리하며 이정도만 알고 있어도 시작하는데는 큰 무리가 없을 것으로 보입니다.

저는 계속 학습하며 빌드 방법까지 소개하는 글을 올려보도록 노력하겠습니다.