기존 리포지토리에 추가

Turborepo는 단일 또는 멀티 패키지 리포지토리에서 점진적으로 채택하여 리포지토리의 개발자 및 CI 워크플로우를 가속화할 수 있습니다.

turbo를 설치하고 turbo.json에서 태스크를 구성한 후, 캐싱이 태스크를 훨씬 빠르게 실행하는 데 어떻게 도움이 되는지 알게 될 것입니다.

단일 패키지 워크스페이스 준비

단일 패키지 워크스페이스는 예를 들어 npx create-next-app 또는 npm create vite를 실행한 후 얻는 것입니다. Turborepo가 리포지토리를 처리하도록 추가 작업을 수행할 필요가 없으므로 아래 첫 번째 단계로 바로 이동할 수 있습니다.

단일 패키지 워크스페이스에서 Turborepo에 대해 자세히 알아보려면 전용 가이드를 참조하세요.

멀티 패키지 워크스페이스(모노레포) 준비

turbo는 JavaScript 생태계의 주요 패키지 매니저의 기능인 워크스페이스 위에 구축되었습니다. 이를 통해 기존 코드베이스에서 쉽게 채택할 수 있습니다.

Good to know:

turbo가 워크스페이스에서 패키지를 발견할 수 없거나 의존성 그래프를 따르지 않는 등의 문제가 있는 경우 팁을 보려면 리포지토리 구조화 페이지를 참조하세요.

turbo를 사용하여 모든 패키지에 대해 모든 태스크를 즉시 실행할 필요는 없습니다. 몇 개의 패키지에서 단일 태스크로 시작하여 Turborepo에 익숙해지면 점진적으로 더 많은 태스크와 패키지를 추가할 수 있습니다.

리포지토리에 Turborepo 추가

`turbo` 설치

최상의 개발자 경험을 위해 turbo를 전역 및 리포지토리 루트에 모두 설치하는 것을 권장합니다.

Ensure you have created a pnpm-workspace.yaml file before you begin the installation. Failure to have this file will result in an error that says: --workspace-root may only be used inside a workspace.

Terminal

# Global install
pnpm add turbo --global
# Install in repository
pnpm add turbo --save-dev --workspace-root

두 설치를 모두 권장하는 이유에 대해 자세히 알아보려면 설치 페이지를 참조하세요.

`turbo.json` 파일 추가

리포지토리의 루트에 turbo.json 파일을 생성합니다.

이 가이드에서는 build 및 check-types 태스크를 사용하지만 lint 또는 test와 같이 관심 있는 다른 태스크로 대체할 수 있습니다.

./turbo.json

{
  "$schema": "https://turborepo.com/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    }
  }
}

turbo.json 구성에 대한 자세한 내용은 구성 옵션 문서를 참조하세요.

Next.js 애플리케이션에서 turbo가 실행할 check-types 스크립트가 있는지 확인하세요.

apps/web/package.json

{
  "scripts": {
+   "check-types": "tsc --noEmit"
  }
}

멀티 패키지 워크스페이스에서는 하나의 turbo 명령으로 여러 패키지에 걸쳐 여러 스크립트가 실행되는 방식을 보기 위해 하나 이상의 라이브러리 패키지에 check-types 스크립트를 추가할 수도 있습니다.

`.gitignore` 편집

.gitignore 파일에 .turbo를 추가합니다. turbo CLI는 로그, 출력 및 기타 기능을 유지하기 위해 이러한 폴더를 사용합니다.

.gitignore

+ .turbo

루트 `package.json`에 `packageManager` 필드 추가

Turborepo는 패키지 매니저의 정보를 사용하여 리포지토리를 최적화합니다. 사용 중인 패키지 매니저를 선언하려면 아직 없는 경우 루트 package.json에 packageManager 필드를 추가하세요.

package.json

{
+  "packageManager": "pnpm@10.0.0"
}

Good to know:

리포지토리에 따라 마이그레이션 중이거나 아직 packageManager 키를 사용할 수 없는 상황에서는 dangerouslyDisablePackageManagerCheck를 사용해야 할 수 있습니다.

패키지 매니저 워크스페이스 설정

멀티 패키지 워크스페이스의 경우 워크스페이스 구조를 인식하도록 패키지 매니저를 구성해야 합니다.

workspaces 필드는 패키지가 포함된 디렉토리를 패키지 매니저에 알려줍니다. 일반적인 패턴으로는 애플리케이션을 위한 apps/*와 공유 라이브러리를 위한 packages/*가 있습니다.

Good to know:

단일 패키지 리포지토리를 사용하는 경우 워크스페이스가 필요하지 않으므로 이 단계를 건너뛸 수 있습니다.

pnpm-workspace.yaml

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

→ pnpm workspace documentation

리포지토리 구조화 방법에 대한 자세한 내용은 리포지토리 구조화를 참조하세요.

`turbo`로 태스크 실행

이제 Turborepo를 사용하여 이전에 turbo.json에 추가한 태스크를 실행할 수 있습니다. 위의 예제 태스크를 사용하면:

Terminal

turbo build check-types

이는 build와 check-types 태스크를 동시에 실행합니다. 워크스페이스의 의존성 그래프가 올바른 순서로 태스크를 실행하는 데 사용됩니다.

코드를 변경하지 않고 build와 check-types를 다시 실행해 보세요:

Terminal

turbo check-types build

다음과 같은 터미널 출력이 표시됩니다:

Terminal

Tasks:    2 successful, 2 total
Cached:    2 cached, 2 total
Time:    185ms >>> FULL TURBO

축하합니다! 밀리초 만에 코드를 빌드하고 타입 체크했습니다.

turbo가 이를 가능하게 하는 방법에 대해 자세히 알아보려면 캐싱 문서를 확인하세요.

`turbo`로 `dev`를 실행하여 개발 시작

멀티 패키지 워크스페이스에서는 turbo dev를 실행하여 모든 패키지에 대한 개발 태스크를 한 번에 시작할 수 있습니다.

Terminal

turbo dev

필터를 사용하여 특정 패키지와 그 의존성에 집중할 수도 있습니다.

단일 패키지 워크스페이스에서는 다음 이유로 이 단계가 큰 가치를 제공하지 않습니다:

개발 태스크에 대한 출력을 캐시하지 않습니다.
개발 스크립트가 하나만 있으므로 병렬로 실행할 것이 없습니다.

다음 단계

이제 Turborepo로 실행 중입니다! 워크플로우를 개선하고 turbo를 최대한 활용할 수 있는 더 많은 방법을 알아보려면 다음 페이지를 확인하는 것을 권장합니다: