turbo.json 설정하기

Workspace의 루트 디렉토리에 turbo.json 파일을 사용하여 turbo의 동작을 설정합니다. 다음과 같은 방법도 사용할 수 있습니다:

더 세밀한 제어를 위해 패키지 설정을 사용합니다.
IDE 지원과 함께 설정에 주석을 추가하려면 turbo.jsonc를 사용합니다.

전역 옵션

`extends`

./apps/web/turbo.json

{
  "extends": ["//"]
}

패키지 설정을 사용하여 패키지에 대한 특정 설정을 만들기 위해 루트 turbo.json을 확장합니다.

extends의 유일한 유효한 값은 루트 turbo.json에서 설정을 상속하기 위한 ["//"]입니다.
루트 turbo.json에서 extends를 사용하면 무시됩니다.

`globalDependencies`

./turbo.json

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

모든 작업 해시에 포함할 glob 목록입니다. 이러한 glob과 일치하는 파일이 변경되면 모든 작업이 캐시를 놓치게 됩니다. glob은 turbo.json의 위치를 기준으로 합니다.

기본적으로 루트 package.json과 lockfile만 전역 해시에 포함되며 무시할 수 없습니다. 추가된 globalDependencies도 전역 해시에 포함됩니다.

glob은 저장소의 소스 제어 루트에 있어야 합니다. 저장소 외부의 glob은 지원되지 않습니다.

`globalEnv`

./turbo.json

{
  "globalEnv": ["GITHUB_TOKEN", "PACKAGE_VERSION", "NODE_ENV"]
}

모든 작업의 해시에 영향을 주려는 환경 변수 목록입니다. 이러한 환경 변수의 모든 변경 사항은 모든 작업이 캐시를 놓치게 합니다.

와일드카드 및 부정 구문에 대한 자세한 내용은 env 섹션을 참조하세요.

`globalPassThroughEnv`

./turbo.json

{
  "globalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
}

작업에 사용할 수 있도록 하려는 환경 변수 목록입니다. 이 키를 사용하면 모든 작업이 엄격한 환경 변수 모드에 선택됩니다.

또한 Turborepo에는 운영 체제 환경 변수와 같은 일반적인 경우를 위한 내장 전역 passthrough 변수 세트가 있습니다. 여기에는 HOME, PATH, APPDATA, SHELL, PWD 등과 같은 변수가 포함됩니다. 전체 목록은 소스 코드에서 찾을 수 있습니다.

Passthrough 값은 캐싱을 위한 해시에 기여하지 않습니다

이러한 변수의 변경 사항이 캐시 미스를 발생시키려면 env 또는 globalEnv에 포함해야 합니다.

`ui`

기본값: "stream"

저장소의 터미널 UI를 선택합니다.

"tui"는 각 로그를 한 번에 보고 작업과 상호 작용할 수 있습니다. "stream"은 로그가 들어오는 대로 출력하며 대화형이 아닙니다.

./turbo.json

{
  "ui": "tui" | "stream"
}

`noUpdateNotifier`

기본값: false

true로 설정하면 새 버전의 turbo를 사용할 수 있을 때 나타나는 업데이트 알림을 비활성화합니다.

./turbo.json

{
  "noUpdateNotifier": true
}

`concurrency`

기본값: "10"

작업 실행의 최대 동시성을 설정/제한합니다. 1 이상의 정수 또는 50%와 같은 백분율 값이어야 합니다.

직렬 실행(한 번에 하나의 작업)을 강제하려면 1을 사용합니다.
사용 가능한 모든 논리 프로세서를 사용하려면 100%를 사용합니다.
--parallel 플래그도 전달되면 이 옵션은 무시됩니다.

./turbo.json

{
  "concurrency": "1"
}

`dangerouslyDisablePackageManagerCheck`

기본값: false

Turborepo는 저장소의 lockfile을 사용하여 캐싱 동작, 패키지 그래프 등을 결정합니다. 이 때문에 Turborepo를 안정화하는 데 도움이 되도록 packageManager 필드를 사용합니다.

점진적 마이그레이션을 돕거나 packageManager 필드를 사용할 수 없는 상황에서 --dangerously-disable-package-manager-check를 사용하여 이 검사를 선택 해제하고 불안정한 lockfile이 예측할 수 없는 동작을 생성할 위험을 감수할 수 있습니다. 비활성화되면 Turborepo는 저장소에 의도된 패키지 매니저를 최선의 노력으로 검색을 시도합니다.

./turbo.json

{
  "dangerouslyDisablePackageManagerCheck": true
}

플래그 또는 TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK 환경 변수를 통해 이 검사를 선택 해제할 수도 있습니다.

`cacheDir`

기본값: ".turbo/cache"

파일 시스템 캐시 디렉토리를 지정합니다.

./turbo.json

{
  "cacheDir": ".turbo/cache"
}

`daemon`

기본값: true

Turborepo는 일부 비용이 많이 드는 작업을 사전 계산하기 위해 백그라운드 프로세스를 실행합니다. 이 독립 실행형 프로세스(daemon)는 성능 최적화이며 turbo의 적절한 기능에는 필요하지 않습니다.

./turbo.json

{
  "daemon": true
}

Good to know:

CI 환경에서 실행할 때 daemon은 이 설정에 관계없이 항상 비활성화됩니다.

`envMode`

기본값: "strict"

Turborepo의 환경 모드를 사용하면 런타임에 작업에 사용할 수 있는 환경 변수를 제어할 수 있습니다:

"strict": turbo.json의 env 및 globalEnv 키에 지정된 환경 변수만 필터링합니다.
"loose": 프로세스의 모든 환경 변수를 사용할 수 있도록 허용합니다.

./turbo.json

{
  "envMode": "strict"
}

환경 모드에 대해 자세히 알아보세요.

`tags` 실험적 기능

./apps/web/turbo.json

{
  "tags": ["utils"]
}

Boundaries와 함께 사용할 패키지에 태그를 추가합니다.

이 키는 패키지 설정에서만 작동합니다. 루트 turbo.json에서 이 키를 사용하면 오류가 발생합니다.

작업 정의하기

`tasks`

tasks 객체의 각 키는 turbo run으로 실행할 수 있는 작업의 이름입니다. Turborepo는 Workspace 설정에 설명된 패키지에서 작업 이름을 가진 package.json의 스크립트를 검색합니다.

작업에 설명된 나머지 설정을 사용하여 Turborepo는 설명된 순서대로 스크립트를 실행하고, 제공된 경우 the outputs 키에 로그와 파일 출력을 캐싱합니다.

아래 예제에서는 tasks 키 아래에 build, test, dev의 세 가지 작업을 정의했습니다.

./turbo.json

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

작업 옵션

tasks에 정의한 작업에서 사용 가능한 옵션을 사용하여 turbo가 작업을 실행하는 방법을 설명할 수 있습니다.

`dependsOn`

작업이 실행을 시작하기 전에 완료해야 하는 작업 목록입니다.

dependsOn 관계에는 세 가지 유형이 있습니다: 의존성 관계, 동일 패키지 관계, 임의 작업 관계.

의존성 관계

dependsOn의 문자열 앞에 ^를 붙이면 turbo에게 패키지의 의존성에 있는 작업이 먼저 완료될 때까지 작업이 기다려야 한다고 알려줍니다. 예를 들어, 아래 turbo.json에서:

./turbo.json

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

turbo는 패키지 그래프의 "하단"에서 시작하여 내부 종속성이 없는 패키지를 찾을 때까지 각 패키지를 재귀적으로 방문합니다. 그런 다음 종속성 체인의 끝에 있는 build 작업을 먼저 실행하고 모든 build 작업이 순서대로 완료될 때까지 "상단"으로 되돌아갑니다.

동일 패키지 관계

^ 접두사가 없는 작업 이름은 동일한 패키지 내의 다른 작업에 의존하는 작업을 설명합니다. 예를 들어, 아래 turbo.json에서:

./turbo.json

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

test 작업은 동일한 패키지에서 lint 및 build 작업이 완료된 후에만 실행됩니다.

임의 작업 관계

특정 패키지 작업 간의 작업 종속성을 지정합니다.

./turbo.json

{
  "tasks": {
    "web#lint": {
      "dependsOn": ["utils#build"]
    }
  }
}

이 turbo.json에서 web#lint 작업은 utils#build 작업이 완료될 때까지 기다립니다.

`env`

작업이 의존하는 환경 변수 목록입니다.

./turbo.json

{
  "tasks": {
    "build": {
      "env": ["DATABASE_URL"] // 모든 build 작업의 해시에 영향을 미침
    },
    "web#build": {
      "env": ["API_SERVICE_KEY"] // web의 build 작업 해시에 영향을 미침
    }
  }
}

Good to know:

Turborepo는 프레임워크 추론을 통해 일반적인 프레임워크의 접두사가 있는 환경 변수를 자동으로 포함합니다. 예를 들어, 패키지가 Next.js 프로젝트인 경우 NEXT_PUBLIC_으로 시작하는 환경 변수를 지정할 필요가 없습니다.

와일드카드

Turborepo는 환경 변수에 대한 와일드카드를 지원하므로 주어진 접두사를 가진 모든 환경 변수를 쉽게 고려할 수 있습니다. 예를 들어, 아래 turbo.json은 MY_API_로 시작하는 모든 환경 변수를 해시에 포함합니다:

./turbo.json

{
  "tasks": {
    "build": {
      "env": ["MY_API_*"]
    }
  }
}

부정

선행 !는 전체 패턴이 부정됨을 의미합니다. 예를 들어, 아래 turbo.json은 MY_API_URL 변수를 무시합니다.

./turbo.json

{
  "tasks": {
    "build": {
      "env": ["!MY_API_URL"]
    }
  }
}

예시

패턴	설명
`"*"`	모든 환경 변수와 일치합니다.
`"!*"`	모든 환경 변수를 제외합니다.
`"FOO*"`	`FOO`, `FOOD`, `FOO_FIGHTERS` 등과 일치합니다.
`"FOO\*"`	`"FOO*"`로 해석되며 `FOO`, `FOOD`, `FOO_FIGHTERS`와 일치합니다.
`"FOO\\*"`	`FOO*`라는 이름의 단일 환경 변수와 일치합니다.
`"!FOO*"`	`FOO`로 시작하는 모든 환경 변수를 제외합니다.
`"\!FOO"`	`"!FOO"`로 해석되며 `!FOO`라는 이름의 단일 환경 변수를 제외합니다.
`"\\!FOO"`	`!FOO`라는 이름의 단일 환경 변수와 일치합니다.
`"FOO!"`	`FOO!`라는 이름의 단일 환경 변수와 일치합니다.

`passThroughEnv`

엄격한 환경 모드에서도 이 작업의 런타임에서 사용할 수 있도록 해야 하는 환경 변수의 허용 목록입니다.

./turbo.json

{
  "tasks": {
    "build": {
      // 값은 `build` 스크립트 내에서 사용 가능합니다
      "passThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
    }
  }
}

passThroughEnv에 제공된 값은 작업의 캐시 키에 기여하지 않습니다. 이러한 변수의 변경 사항이 캐시 미스를 발생시키려면 env 또는 globalEnv에 포함해야 합니다.

`outputs`

작업이 성공적으로 완료될 때 캐시할 패키지의 package.json을 기준으로 한 파일 glob 패턴 목록입니다.

출력 경로가 저장소 루트를 기준으로 해야 하는 경우 $TURBO_ROOT$ 를 참조하세요.

./turbo.json

{
  "tasks": {
    "build": {
      // 패키지의 `dist` 디렉토리로 출력된 모든 파일을 캐시
      "outputs": ["dist/**"]
    }
  }
}

이 키를 생략하거나 빈 배열을 전달하면 turbo는 아무것도 캐시하지 않습니다(캐싱이 활성화된 경우 항상 캐시되는 로그 제외).

`cache`

기본값: true

작업 출력을 캐시할지 여부를 정의합니다. cache를 false로 설정하면 장기 실행 개발 작업에 유용하며 작업이 작업 실행 그래프에 있을 때 항상 실행되도록 합니다.

./turbo.json

{
  "tasks": {
    "build": {
      "outputs": [".svelte-kit/**", "dist/**"] // 파일 출력이 캐시됩니다
    },
    "dev": {
      "cache": false, // 출력이 캐시되지 않습니다
      "persistent": true
    }
  }
}

`inputs`

기본값: [], 소스 제어에 체크인된 패키지의 모든 파일

패키지가 변경되었는지 확인할 때 고려할 패키지의 package.json을 기준으로 한 파일 glob 패턴 목록입니다. 명시적으로 무시하려고 해도 다음 파일은 항상 입력으로 간주됩니다:

package.json
turbo.json
패키지 매니저 lockfile

globbing 구문에 대한 자세한 내용은 파일 glob 사양을 참조하세요.

./turbo.json

{
  "tasks": {
    "test": {
      "inputs": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"]
    }
  }
}

inputs 키를 사용하면 .gitignore를 고려하는 turbo의 기본 동작을 선택 해제합니다. 원하는 대로 .gitignore에서 glob을 재구성하거나 $TURBO_DEFAULT$ 를 사용하여 기본 동작을 기반으로 빌드해야 합니다.

$TURBO_DEFAULT$

inputs 키를 지정하면 즉시 기본 동작을 선택 해제하므로 inputs 배열 내에서 특수 문자열 $TURBO_DEFAULT$ 를 사용하여 turbo의 기본 동작을 복원할 수 있습니다. 이를 통해 더 세밀하게 기본 동작을 조정할 수 있습니다.

./turbo.json

{
  "tasks": {
    "check-types": {
      // 패키지의 README를 제외한 모든 기본 입력을 고려
      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
    }
  }
}

$TURBO_ROOT$

작업은 디렉토리 외부에 있는 파일을 참조할 수 있습니다.

파일 glob을 $TURBO_ROOT$ 로 시작하면 glob이 패키지 디렉토리 대신 저장소의 루트를 기준으로 변경됩니다.

./turbo.json

{
  "tasks": {
    "check-types": {
      // `src/`의 모든 Typescript 파일과 루트 tsconfig.json을 입력으로 고려
      "inputs": ["$TURBO_ROOT$/tsconfig.json", "src/**/*.ts"]
    }
  }
}

`outputLogs`

기본값: full

출력 로깅 자세한 정도를 설정합니다. --output-logs CLI 옵션으로 재정의할 수 있습니다.

옵션	설명
`full`	모든 로그를 표시합니다
`hash-only`	작업의 해시만 표시합니다
`new-only`	캐시 미스의 로그만 표시합니다
`errors-only`	작업 실패의 로그만 표시합니다
`none`	모든 작업 로그를 숨깁니다

./turbo.json

{
  "tasks": {
    "build": {
      "outputLogs": "new-only"
    }
  }
}

`persistent`

기본값: false

작업을 persistent로 레이블하여 다른 작업이 장기 실행 프로세스에 의존하지 못하도록 방지합니다. 지속적인 작업은 기본적으로 interactive로 설정됩니다.

장기 실행 프로세스는 종료되지 않기 때문에 이에 의존하는 작업은 절대 실행되지 않습니다. 작업을 persistent로 레이블하면 다른 작업이 이에 의존하는 경우 turbo에서 오류를 발생시킵니다.

이 옵션은 개발 서버나 다른 "watch" 작업에 가장 유용합니다.

./turbo.json

{
  "tasks": {
    "dev": {
      "persistent": true
    }
  }
}

persistent로 표시된 작업은 기본적으로 interactive이기도 합니다.

`interactive`

기본값: false (persistent로 표시된 작업의 경우 기본값이 true)

작업을 interactive로 레이블하여 터미널 UI에서 stdin의 입력을 받을 수 있도록 합니다. persistent와 함께 사용해야 합니다.

이 옵션은 Jest나 Vitest와 같이 실행 중에 조작할 수 있는 스크립트에 가장 유용합니다.

./turbo.json

{
  "tasks": {
    "test:watch": {
      "interactive": true,
      "persistent": true
    }
  }
}

`interruptible`

기본값: false

persistent 작업을 interruptible로 레이블하여 turbo watch에서 다시 시작할 수 있도록 허용합니다.

turbo watch는 패키지의 변경 사항을 감시하고 영향을 받는 작업을 자동으로 다시 시작합니다. 그러나 작업이 persistent인 경우 기본적으로 다시 시작되지 않습니다. persistent 작업을 다시 시작하려면 interruptible을 true로 설정하세요.

`with`

이 작업과 함께 실행될 작업 목록입니다. 이는 항상 동시에 실행되도록 하려는 장기 실행 작업에 가장 유용합니다.

./apps/web/turbo.json

{
  "tasks": {
    "dev": {
      "with": ["api#dev"],
      "persistent": true,
      "cache": false
    }
  }
}

Boundaries

The boundaries tag allows you to define rules for the boundaries command.

./turbo.json

{
  "boundaries": {}
}

`tags`

Each key in the tags object is the name of a tag that can be checked with turbo boundaries.

In the configuration object for a tag, you can define rules for dependencies and dependents.

`dependencies` and `dependents`

Rules for a tag's dependencies and dependents.

You can add an allowlist and a denylist:

./turbo.json

{
  "boundaries": {
    "utils": {
      "dependencies": {
        // permit only packages with the `ui` tag
        "allow": ["ui"],
        // and ban packages with the `unsafe` tag
        "deny": ["unsafe"]
      }
    }
  }
}

Both the allowlist and the denylist can be omitted.

./turbo.json

{
  "boundaries": {
    "utils": {
      "dependencies": {
        // only packages with the `unsafe` tag are banned, all other packages permitted
        "deny": ["unsafe"]
      }
    }
  }
}

Rules can also be added for a tag's dependents, i.e. packages that import this tag.

./turbo.json

{
  "boundaries": {
    "utils": {
      "dependents": {
        // only packages with the `web` tag can import packages with the `utils` tag
        "allow": ["web"]
      }
    }
  }
}

Remote caching

The global remoteCache option has a variety of fields for configuring remote cache usage

./turbo.json

{
  "remoteCache": {}
}

`enabled`

Default: true

Enables remote caching.

When false, Turborepo will disable all remote cache operations, even if the repo has a valid token. If true, remote caching is enabled, but still requires the user to login and link their repo to a remote cache.

`signature`

Default: false

Enables signature verification for requests to the remote cache. When true, Turborepo will sign every uploaded artifact using the value of the environment variable TURBO_REMOTE_CACHE_SIGNATURE_KEY. Turborepo will reject any downloaded artifacts that have an invalid signature or are missing a signature.