bunfig.toml

Bun 의 동작은 설정 파일인 bunfig.toml 을 사용하여 구성할 수 있습니다.

일반적으로 Bun 은 package.json 과 tsconfig.json 과 같은 기존 설정 파일을 사용하여 동작을 구성합니다. bunfig.toml 은 Bun 고유의 것들을 구성할 때만 필요합니다. 이 파일은 선택 사항이며 Bun 은 이 파일 없이도 바로 작동합니다.

전역 vs 로컬

일반적으로 package.json 과 함께 프로젝트 루트에 bunfig.toml 파일을 추가하는 것이 권장됩니다.

Bun 을 전역으로 구성하려면 다음 경로 중 하나에 .bunfig.toml 파일을 생성할 수도 있습니다.

$HOME/.bunfig.toml
$XDG_CONFIG_HOME/.bunfig.toml

전역과 로컬 bunfig 가 모두 감지되면 결과가 얕게 병합되며 로컬이 전역보다 우선합니다. CLI 플래그는 해당되는 경우 bunfig 설정을 재정의합니다.

런타임

Bun 의 런타임 동작은 bunfig.toml 파일의 최상위 필드를 사용하여 구성됩니다.

`preload`

파일이나 스크립트를 실행하기 전에 실행할 스크립트/플러그인 배열입니다.

toml

# `bun run` 으로 파일이나 스크립트를 실행하기 전에 실행할 스크립트
# 이 목록에 플러그인을 추가하여 등록
preload = ["./preload.ts"]

`jsx`

Bun 이 JSX 를 처리하는 방식을 구성합니다. tsconfig.json 의 compilerOptions 에서 이러한 필드를 설정할 수도 있지만, 비 TypeScript 프로젝트에서도 여기에서 지원됩니다.

toml

jsx = "react"
jsxFactory = "h"
jsxFragment = "Fragment"
jsxImportSource = "react"

이 필드에 대한 자세한 내용은 tsconfig 문서를 참조하세요.

`smol`

smol 모드를 활성화합니다. 이는 성능을 희생하면서 메모리 사용량을 줄입니다.

toml

# 성능을 희생하면서 메모리 사용량 줄이기
smol = true

`logLevel`

로그 레벨을 설정합니다. "debug", "warn", "error" 중 하나일 수 있습니다.

toml

logLevel = "debug" # "debug" | "warn" | "error"

`define`

define 필드는 특정 전역 식별자를 상수 식으로 대체할 수 있게 합니다. Bun 은 식별자의 모든 사용을 식으로 대체합니다. 식은 JSON 문자열이어야 합니다.

toml

[define]
# "process.env.bagel" 의 모든 사용을 `lox` 문자열로 대체
# 값은 JSON 으로 파싱되며, 단일 인용부호 문자열이 지원되고 `'undefined'` 는 JS 에서 `undefined` 가 됩니다
# 이것은 향후 릴리스에서 일반 TOML 대신 일반 TOML 이 될 가능성이 높습니다. CLI 인수 파싱에서 넘어온 것입니다
"process.env.bagel" = "'lox'"

`loader`

Bun 이 파일 확장자를 로더에 매핑하는 방식을 구성합니다. 이는 Bun 에서 기본적으로 지원하지 않는 파일을 로드할 때 유용합니다.

toml

[loader]
# .bagel 파일을 임포트할 때 tsx 파일처럼 처리
".bagel" = "tsx"

Bun 은 다음 로더를 지원합니다.

jsx
js
ts
tsx
css
file
json
toml
wasm
napi
base64
dataurl
text

`telemetry`

telemetry 필드는 분석을 활성화/비활성화하는 데 사용됩니다. 기본적으로 telemetry 는 활성화되어 있습니다. 이는 DO_NOT_TRACK 환경 변수와 동일합니다.

현재는 telemetry 를 수집하지 않으며 이 설정은 익명 충돌 보고서의 활성화/비활성화에만 사용되지만, 향후에는 어떤 Bun API 가 가장 많이 사용되는지 또는 bun build 가 얼마나 걸리는지와 같은 정보를 수집할 계획입니다.

toml

telemetry = false

`console`

콘솔 출력 동작을 구성합니다.

`console.depth`

console.log() 객체 검사의 기본 깊이를 설정합니다. 기본값은 2 입니다.

toml

[console]
depth = 3

이는 콘솔 출력에 중첩된 객체가 얼마나 깊게 표시되는지 제어합니다. 높은 값은 더 많은 중첩 속성을 표시하지만 복잡한 객체의 경우 출력이 장황해질 수 있습니다. 이 설정은 --console-depth CLI 플래그로 재정의할 수 있습니다.

테스트 러너

테스트 러너는 bunfig.toml 의 [test] 섹션에서 구성됩니다.

toml

[test]
# 여기에 설정

`test.root`

테스트를 실행할 루트 디렉토리입니다. 기본값은 . 입니다.

toml

[test]
root = "./__tests__"

`test.preload`

최상위 preload 필드와 동일하지만 bun test 에만 적용됩니다.

toml

[test]
preload = ["./setup.ts"]

`test.smol`

최상위 smol 필드와 동일하지만 bun test 에만 적용됩니다.

toml

[test]
smol = true

`test.coverage`

커버리지 보고를 활성화합니다. 기본값은 false 입니다. 재정의하려면 --coverage 를 사용하세요.

toml

[test]
coverage = false

`test.coverageThreshold`

커버리지 임계값을 지정합니다. 기본적으로 임계값은 설정되지 않습니다. 테스트 스위트가 이 임계값을 충족하거나 초과하지 못하면 bun test 는 실패를 나타내기 위해 0 이 아닌 종료 코드로 종료됩니다.

toml

[test]

# 90% 의 라인 레벨 및 함수 레벨 커버리지를 요구하려면
coverageThreshold = 0.9

라인별, 함수별, 문장별 커버리지에 대해 다른 임계값을 지정할 수 있습니다.

toml

[test]
coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }

`test.coverageSkipTestFiles`

커버리지 통계를 계산할 때 테스트 파일을 건너뛸지 여부입니다. 기본값은 false 입니다.

toml

[test]
coverageSkipTestFiles = false

`test.coveragePathIgnorePatterns`

glob 패턴을 사용하여 커버리지 보고서에서 특정 파일이나 파일 패턴을 제외합니다. 단일 문자열 패턴 또는 패턴 배열일 수 있습니다.

toml

[test]
# 단일 패턴
coveragePathIgnorePatterns = "**/*.spec.ts"

# 여러 패턴
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

`test.coverageReporter`

기본적으로 커버리지 보고서는 콘솔에 출력됩니다. CI 환경과 다른 도구에서 지속적인 커버리지 보고서를 사용하려면 lcov 를 사용하세요.

toml

[test]
coverageReporter  = ["text", "lcov"]  # 기본값 ["text"]

`test.coverageDir`

커버리지 보고서가 저장될 경로를 설정합니다. 이는 lcov 와 같은 지속적인 coverageReporter 에 대해서만 작동합니다.

toml

[test]
coverageDir = "path/to/somewhere"  # 기본값 "coverage"

`test.randomize`

테스트를 무작위 순서로 실행합니다. 기본값은 false 입니다.

toml

[test]
randomize = true

이는 매번 다른 순서로 테스트를 실행하여 테스트 상호 의존성과 관련된 버그를 잡는 데 도움이 됩니다. seed 와 결합하면 무작위 순서를 재현할 수 있습니다.

--randomize CLI 플래그는 지정된 경우 이 설정을 재정의합니다.

`test.seed`

테스트 무작위화를 위한 무작위 seed 를 설정합니다. 이 옵션은 randomize 가 true 여야 합니다.

toml

[test]
randomize = true
seed = 2444615283

seed 를 사용하면 실행 간에 무작위 테스트 순서를 재현할 수 있어 flaky 테스트를 디버깅할 때 유용합니다. 무작위 활성화 시 테스트 실패가 발생하면 동일한 seed 를 사용하여 정확한 테스트 순서를 재현할 수 있습니다.

--seed CLI 플래그는 지정된 경우 이 설정을 재정의합니다.

`test.rerunEach`

각 테스트 파일을 지정된 횟수만큼 다시 실행합니다. 기본값은 0(한 번 실행) 입니다.

toml

[test]
rerunEach = 3

이는 flaky 테스트나 비결정적 동작을 잡는 데 유용합니다. 각 테스트 파일은 지정된 횟수만큼 실행됩니다.

--rerun-each CLI 플래그는 지정된 경우 이 설정을 재정의합니다.

`test.concurrentTestGlob`

자동으로 일치하는 테스트 파일을 동시 테스트 실행이 활성화된 상태로 실행하기 위한 glob 패턴을 지정합니다. 이 패턴과 일치하는 테스트 파일은 --concurrent 플래그가 전달된 것처럼 동작하여 해당 파일 내의 모든 테스트를 동시에 실행합니다.

toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"

이는 다음에 유용합니다.

테스트 스위트를 동시 실행으로 점진적으로 마이그레이션
유닛 테스트는 순차적으로 유지하면서 통합 테스트는 동시에 실행
빠른 동시 테스트를 순차 실행이 필요한 테스트와 분리

--concurrent CLI 플래그는 지정된 경우 이 설정을 재정의합니다.

`test.onlyFailures`

활성화되면 출력에 실패한 테스트만 표시됩니다. 이는 통과한 테스트를 숨겨서 대규모 테스트 스위트의 노이즈를 줄이는 데 도움이 됩니다. 기본값은 false 입니다.

toml

[test]
onlyFailures = true

이는 bun test 실행 시 --only-failures 플래그를 사용하는 것과 동일합니다.

`test.reporter`

테스트 보고서 설정을 구성합니다.

`test.reporter.dots`

각 테스트에 대해 점을 표시하는 간결한 출력인 dots 보고서를 활성화합니다. 기본값은 false 입니다.

toml

[test.reporter]
dots = true

`test.reporter.junit`

JUnit XML 보고를 활성화하고 출력 파일 경로를 지정합니다.

toml

[test.reporter]
junit = "test-results.xml"

이는 CI 시스템과 다른 도구에서 사용할 수 있는 JUnit XML 보고서를 생성합니다.

패키지 매니저

패키지 관리는 복잡한 문제입니다. 다양한 사용 사례를 지원하기 위해 bun install 의 동작은 [install] 섹션에서 구성할 수 있습니다.

toml

[install]
# 여기에 설정

`install.optional`

선택적 의존성을 설치할지 여부입니다. 기본값은 true 입니다.

toml

[install]
optional = true

`install.dev`

개발 의존성을 설치할지 여부입니다. 기본값은 true 입니다.

toml

[install]
dev = true

`install.peer`

피어 의존성을 설치할지 여부입니다. 기본값은 true 입니다.

toml

[install]
peer = true

`install.production`

bun install 이 "프로덕션 모드"로 실행될지 여부입니다. 기본값은 false 입니다.

프로덕션 모드에서는 "devDependencies" 가 설치되지 않습니다. CLI 에서 --production 을 사용하여 이 설정을 재정의할 수 있습니다.

toml

[install]
production = false

`install.exact`

package.json 에 정확한 버전을 설정할지 여부입니다. 기본값은 false 입니다.

기본적으로 Bun 은 캐럿 범위를 사용합니다. 패키지의 latest 버전이 2.4.1 이면 package.json 의 버전 범위는 ^2.4.1 이 됩니다. 이는 2.4.1 부터 3.0.0 미만 (포함하지 않음) 까지의 모든 버전이 허용됨을 나타냅니다.

toml

[install]
exact = false

`install.saveTextLockfile`

false 인 경우, bun install 실행 시 lockfile 이 없을 때 텍스트 기반 bun.lock 대신 이진 bun.lockb 를 생성합니다.

기본값은 true(Bun v1.2 부터).

toml

[install]
saveTextLockfile = false

`install.auto`

Bun 의 패키지 자동 설치 동작을 구성합니다. 기본값은 "auto" — node_modules 폴더가 없을 때 Bun 은 실행 중에 자동으로 의존성을 즉시 설치합니다.

toml

[install]
auto = "auto"

유효한 값은 다음과 같습니다.

값	설명
`"auto"`	로컬 `node_modules` 가 있으면 해당 모듈에서 해결합니다. 그렇지 않으면 실행 중에 의존성을 자동으로 설치합니다.
`"force"`	`node_modules` 가 있더라도 항상 의존성을 자동으로 설치합니다.
`"disable"`	의존성을 자동으로 설치하지 않습니다.
`"fallback"`	로컬 `node_modules` 를 먼저 확인한 다음 찾을 수 없는 패키지를 자동으로 설치합니다. CLI 에서 `bun -i` 로 활성화할 수 있습니다.

`install.frozenLockfile`

true 인 경우, bun install 은 bun.lock 을 업데이트하지 않습니다. 기본값은 false 입니다. package.json 과 기존 bun.lock 이 일치하지 않으면 오류가 발생합니다.

toml

[install]
frozenLockfile = false

`install.dryRun`

bun install 이 실제로 의존성을 설치할지 여부입니다. 기본값은 false 입니다. true 인 경우, 모든 bun install 명령에 --dry-run 을 설정한 것과 동일합니다.

toml

[install]
dryRun = false

`install.globalDir`

Bun 이 전역 설치된 패키지를 배치하는 디렉토리를 구성합니다.

환경 변수: BUN_INSTALL_GLOBAL_DIR

toml

[install]
# `bun install --global` 이 패키지를 설치하는 위치
globalDir = "~/.bun/install/global"

`install.globalBinDir`

Bun 이 전역 설치된 바이너리와 CLI 를 설치하는 디렉토리를 구성합니다.

환경 변수: BUN_INSTALL_BIN

toml

[install]
# 전역 설치된 패키지 바이너리가 링크되는 위치
globalBinDir = "~/.bun/bin"

`install.registry`

기본 레지스트리는 https://registry.npmjs.org/ 입니다. 이는 bunfig.toml 에서 전역으로 구성할 수 있습니다.

toml

[install]
# 문자열로 기본 레지스트리 설정
registry = "https://registry.npmjs.org"
# 토큰 설정
registry = { url = "https://registry.npmjs.org", token = "123456" }
# 사용자 이름/비밀번호 설정
registry = "https://username:password@registry.npmjs.org"

`install.linkWorkspacePackages`

워크스페이스 패키지가 어떻게 링크되는지 구성하려면 install.linkWorkspacePackages 옵션을 사용하세요.

모노레포 루트에서 각각의 node_modules 디렉토리로 워크스페이스 패키지를 링크할지 여부입니다. 기본값은 true 입니다.

toml

[install]
linkWorkspacePackages = true

`install.scopes`

특정 scope(예: @myorg/<package>) 에 대한 레지스트리를 구성하려면 install.scopes 를 사용하세요. $variable 표기법으로 환경 변수를 참조할 수 있습니다.

toml

[install.scopes]
# 문자열로 레지스트리
myorg = "https://username:password@registry.myorg.com/"

# 사용자 이름/비밀번호로 레지스트리
# 환경 변수를 참조할 수 있습니다
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

# 토큰으로 레지스트리
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }

`install.ca` 및 `install.cafile`

CA 인증서를 구성하려면 install.ca 또는 install.cafile 를 사용하여 CA 인증서 파일의 경로를 지정하세요.

toml

[install]
# 문자열로 CA 인증서
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# CA 인증서 파일 경로. 파일에는 여러 인증서가 포함될 수 있습니다.
cafile = "path/to/cafile"

`install.cache`

캐시 동작을 구성합니다.

toml

[install.cache]

# 캐시에 사용할 디렉토리
dir = "~/.bun/install/cache"

# true 인 경우, 전역 캐시에서 로드하지 않음
# Bun 은 여전히 node_modules/.cache 에 쓸 수 있습니다
disable = false

# true 인 경우, 항상 레지스트리에서 최신 버전 해결
disableManifest = false

`install.lockfile`

lockfile 동작을 구성하려면 install.lockfile 섹션을 사용하세요.

bun install 시 lockfile 을 생성할지 여부입니다. 기본값은 true 입니다.

toml

[install.lockfile]
save = true

bun.lock 과 함께 비 Bun lockfile 을 생성할지 여부입니다. (bun.lock 은 항상 생성됩니다.) 현재 "yarn" 만 지원되는 값입니다.

toml

[install.lockfile]
print = "yarn"

`install.linker`

의존성 설치를 위한 링커 전략을 구성합니다. 새로운 워크스페이스의 경우 기본값은 "isolated", 새로운 단일 패키지 프로젝트와 기존 프로젝트 (v1.3.2 이전) 의 경우 "hoisted" 입니다.

전체 문서는 패키지 매니저 > 격리된 설치 를 참조하세요.

toml

[install]
linker = "hoisted"

유효한 값은 다음과 같습니다.

값	설명
`"hoisted"`	공유 `node_modules` 디렉토리에 의존성 링크
`"isolated"`	각 패키지 설치 내부에 의존성 링크

toml

[debug]
# blob: 또는 src: 링크로 이동할 때 편집기에서 파일 열기
# 그렇지 않으면 $EDITOR 또는 $VISUAL 시도
# 그래도 실패하면 Visual Studio Code, 그 다음 Sublime Text, 그 다음 다른 것들 시도
# Bun.openInEditor() 에서 사용됨
editor = "code"

# 편집기 목록:
# - "subl", "sublime"
# - "vscode", "code"
# - "textmate", "mate"
# - "idea"
# - "webstorm"
# - "nvim", "neovim"
# - "vim","vi"
# - "emacs"

`install.security.scanner`

설치 전에 패키지의 취약점을 스캔하는 보안 스캐너를 구성합니다.

먼저 npm 에서 보안 스캐너를 설치합니다.

bash

bun add -d @acme/bun-security-scanner

그런 다음 bunfig.toml 에서 구성합니다.

toml

[install.security]
scanner = "@acme/bun-security-scanner"

보안 스캐너가 구성되면:

보안을 위해 자동 설치가 자동으로 비활성화됨
설치 전에 패키지 스캔
치명적인 문제가 발견되면 설치 취소
설치 중 보안 경고 표시

보안 스캐너 사용 및 작성 에 대해 자세히 알아보세요.

`install.minimumReleaseAge`

npm 패키지 버전의 최소 연령 (초) 을 구성합니다. 이 임계값보다 최근에 게시된 패키지 버전은 설치 중에 필터링됩니다. 기본값은 null(비활성화) 입니다.

toml

[install]
# 최소 3 일 전에 게시된 패키지 버전만 설치
minimumReleaseAge = 259200
# 이 패키지들은 3 일 최소 연령 요구사항을 우회합니다
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

자세한 내용은 설치 문서의 최소 릴리스 연령 을 참조하세요.

`bun run`

bun run 명령은 [run] 섹션에서 구성할 수 있습니다. 이는 bun run 명령과 파일이나 실행 파일 또는 스크립트를 실행할 때 bun 명령에 적용됩니다.

현재 bunfig.toml 은 로컬 프로젝트에서 bun run 에 대해서만 자동으로 로드됩니다 (전역 .bunfig.toml 을 확인하지 않음).

`run.shell` - 시스템 셸 또는 Bun 의 셸 사용

bun run 또는 bun 을 통해 package.json 스크립트를 실행할 때 사용할 셸입니다. Windows 에서는 기본적으로 "bun" 이며, 다른 플랫폼에서는 기본적으로 "system" 입니다.

항상 Bun 의 셸 대신 시스템 셸을 사용하려면 (Windows 가 아닌 경우 기본 동작):

toml

[run]
# Windows 가 아닌 경우 기본값
shell = "system"

항상 시스템 셸 대신 Bun 의 셸을 사용하려면:

toml

[run]
# Windows 에서 기본값
shell = "bun"

`run.bun` - `node` 를 `bun` 으로 자동 별칭

true 인 경우, bun run 또는 bun 이 호출하는 모든 스크립트나 실행 파일에 대해 $PATH 에 bun 바이너리를 가리키는 node 심볼릭 링크를 추가합니다.

이는 node 를 실행하는 스크립트가 있으면 스크립트를 변경하지 않고도 대신 bun 이 실행된다는 것을 의미합니다. 이는 재귀적으로 작동하므로 스크립트가 node 를 실행하는 다른 스크립트를 실행하면 대신 bun 이 실행됩니다. 이는 shebang 에도 적용되므로 node 를 가리키는 shebang 이 있는 스크립트가 있으면 대신 bun 이 실행됩니다.

기본적으로 node 가 $PATH 에 없으면 활성화됩니다.

toml

[run]
# 모든 `bun run` 명령에 `bun --bun` 과 동일
bun = true

다음 명령으로 테스트할 수 있습니다.

bun --bun which node # /path/to/bun
bun which node # /path/to/node

이 옵션은 모든 bun run 명령에 --bun 을 접두사로 추가하는 것과 동일합니다.

bun --bun run dev
bun --bun dev
bun run --bun dev

false 로 설정하면 node 심볼릭 링크가 비활성화됩니다.

`run.silent` - 실행 중인 명령 보고 억제

true 인 경우, bun run 또는 bun 이 실행하는 명령의 출력을 억제합니다.

toml

[run]
silent = true

이 옵션이 없으면 실행 중인 명령이 콘솔에 출력됩니다.

bun run dev
echo "Running \"dev\"..."

txt

Running "dev"...

이 옵션이 있으면 실행 중인 명령이 콘솔에 출력되지 않습니다.

bun run dev

txt

Running "dev"...

이는 모든 bun run 명령에 --silent 를 전달하는 것과 동일합니다.

bun --silent run dev
bun --silent dev
bun run --silent dev

전역 vs 로컬 ​

런타임 ​

preload ​

jsx ​

smol ​

logLevel ​

define ​

loader ​

telemetry ​

console ​

console.depth ​

테스트 러너 ​

test.root ​

test.preload ​

test.smol ​

test.coverage ​

test.coverageThreshold ​

test.coverageSkipTestFiles ​

test.coveragePathIgnorePatterns ​

test.coverageReporter ​

test.coverageDir ​

test.randomize ​

test.seed ​

test.rerunEach ​

test.concurrentTestGlob ​

test.onlyFailures ​

test.reporter ​

test.reporter.dots ​

test.reporter.junit ​

패키지 매니저 ​

install.optional ​

install.dev ​

install.peer ​

install.production ​

install.exact ​

install.saveTextLockfile ​

install.auto ​

install.frozenLockfile ​

install.dryRun ​

install.globalDir ​

install.globalBinDir ​

install.registry ​

install.linkWorkspacePackages ​

install.scopes ​

install.ca 및 install.cafile ​

install.cache ​

install.lockfile ​

install.linker ​

install.security.scanner ​

install.minimumReleaseAge ​

bun run ​

run.shell - 시스템 셸 또는 Bun 의 셸 사용 ​

run.bun - node 를 bun 으로 자동 별칭 ​

run.silent - 실행 중인 명령 보고 억제 ​

전역 vs 로컬

런타임

`preload`

`jsx`

`smol`

`logLevel`

`define`

`loader`

`telemetry`

`console`

`console.depth`

테스트 러너

`test.root`

`test.preload`

`test.smol`

`test.coverage`

`test.coverageThreshold`

`test.coverageSkipTestFiles`

`test.coveragePathIgnorePatterns`

`test.coverageReporter`

`test.coverageDir`

`test.randomize`

`test.seed`

`test.rerunEach`

`test.concurrentTestGlob`

`test.onlyFailures`

`test.reporter`

`test.reporter.dots`

`test.reporter.junit`

패키지 매니저

`install.optional`

`install.dev`

`install.peer`

`install.production`

`install.exact`

`install.saveTextLockfile`

`install.auto`

`install.frozenLockfile`

`install.dryRun`

`install.globalDir`

`install.globalBinDir`

`install.registry`

`install.linkWorkspacePackages`

`install.scopes`

`install.ca` 및 `install.cafile`

`install.cache`

`install.lockfile`

`install.linker`

`install.security.scanner`

`install.minimumReleaseAge`

`bun run`

`run.shell` - 시스템 셸 또는 Bun 의 셸 사용

`run.bun` - `node` 를 `bun` 으로 자동 별칭

`run.silent` - 실행 중인 명령 보고 억제