bunfig.toml

Поведение Bun может быть настроено с помощью файла конфигурации bunfig.toml.

В целом Bun полагается на существующие файлы конфигурации, такие как package.json и tsconfig.json, для настройки своего поведения. bunfig.toml необходим только для настройки специфичных для Bun вещей. Этот файл является опциональным, и Bun будет работать из коробки без него.

Глобальная vs. локальная

В целом рекомендуется добавить файл bunfig.toml в корень вашего проекта, рядом с package.json.

Для глобальной настройки 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. Вы также можете установить эти поля в compilerOptions вашего tsconfig.json, но они также поддерживаются здесь для проектов, не использующих 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'` становится `undefined` в JS.
# Вероятно, в будущем выпуске это изменится на обычный 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 используется для включения/отключения аналитики. По умолчанию телеметрия включена. Это эквивалентно переменной окружения DO_NOT_TRACK.

В настоящее время мы не собираем телеметрию, и эта настройка используется только для включения/отключения анонимных отчётов о сбоях, но в будущем мы планируем собирать информацию, такую как то, какие API Bun используются чаще всего или сколько времени занимает bun build.

toml

telemetry = false

`console`

Настройка поведения вывода консоли.

`console.depth`

Установить глубину по умолчанию для проверки объектов console.log(). По умолчанию 2.

toml

[console]
depth = 3

Это управляет тем, насколько глубоко вложенные объекты отображаются в выводе консоли. Более высокие значения показывают больше вложенных свойств, но могут создавать многословный вывод для сложных объектов. Эта настройка может быть переопределена флагом CLI --console-depth.

Устройство для тестирования

Устройство для тестирования настраивается в разделе [test] вашего bunfig.toml.

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 завершится с ненулевым кодом выхода, указывающим на неудачу.

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`

Установить путь, где будут сохранены отчёты о покрытии. Обратите внимание, что это работает только для постоянных coverageReporter, таких как lcov.

toml

[test]
coverageDir = "path/to/somewhere"  # по умолчанию "coverage"

`test.randomize`

Запускать тесты в случайном порядке. По умолчанию false.

toml

[test]
randomize = true

Это помогает выявить ошибки, связанные с взаимозависимостями тестов, запуская тесты в разном порядке каждый раз. В сочетании с seed случайный порядок становится воспроизводимым.

Флаг CLI --randomize переопределит эту настройку при указании.

`test.seed`

Установить случайное зерно для рандомизации тестов. Эта опция требует, чтобы randomize было true.

toml

[test]
randomize = true
seed = 2444615283

Использование зерна делает рандомизированный порядок тестов воспроизводимым между запусками, что полезно для отладки нестабильных тестов. Когда вы сталкиваетесь с неудачей теста с включённой рандомизацией, вы можете использовать то же зерно для воспроизведения точного порядка тестов.

Флаг CLI --seed переопределит эту настройку при указании.

`test.rerunEach`

Перезапускать каждый тестовый файл указанное количество раз. По умолчанию 0 (запуск один раз).

toml

[test]
rerunEach = 3

Это полезно для выявления нестабильных тестов или недетерминированного поведения. Каждый тестовый файл будет выполнен указанное количество раз.

Флаг CLI --rerun-each переопределит эту настройку при указании.

`test.concurrentTestGlob`

Указать шаблон glob для автоматического запуска соответствующих тестовых файлов с включённым параллельным выполнением тестов. Тестовые файлы, соответствующие этому шаблону, будут вести себя так, как будто был передан флаг --concurrent, запуская все тесты внутри этих файлов параллельно.

toml

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

Это полезно для:

Постепенной миграции наборов тестов на параллельное выполнение
Параллельного запуска интеграционных тестов при сохранении последовательного выполнения модульных тестов
Разделения быстрых параллельных тестов от тестов, требующих последовательного выполнения

Флаг CLI --concurrent переопределит эту настройку при указании.

`test.onlyFailures`

При включении только неудачные тесты отображаются в выводе. Это помогает уменьшить шум в больших наборах тестов, скрывая проходящие тесты. По умолчанию false.

toml

[test]
onlyFailures = true

Это эквивалентно использованию флага --only-failures при запуске bun test.

`test.reporter`

Настройте параметры отчётности тестов.

`test.reporter.dots`

Включить отчётчик dots, который отображает компактный вывод, показывая точку для каждого теста. По умолчанию false.

toml

[test.reporter]
dots = true

`test.reporter.junit`

Включить отчётность JUnit XML и указать путь к выходному файлу.

toml

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

Это генерирует отчёт JUnit XML, который может быть потреблён системами CI и другими инструментами.

Менеджер пакетов

Управление пакетами — сложная задача; для поддержки ряда случаев использования поведение 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" не устанавливаются. Вы можете использовать --production в CLI для переопределения этой настройки.

toml

[install]
production = false

`install.exact`

Устанавливать ли точную версию в package.json. По умолчанию false.

По умолчанию Bun использует диапазоны caret; если последняя версия пакета — 2.4.1, диапазон версий в вашем package.json будет ^2.4.1. Это указывает, что любая версия от 2.4.1 до (но не включая) 3.0.0 приемлема.

toml

[install]
exact = false

`install.saveTextLockfile`

Если false, генерировать бинарный bun.lockb вместо текстового файла bun.lock при запуске bun install и отсутствии файла блокировки.

По умолчанию 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, это эквивалентно установке --dry-run для всех команд bun install.

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`

Для настройки реестра для определённой области (например, @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`

Для настройки поведения файла блокировки используйте раздел install.lockfile.

Генерировать ли файл блокировки при bun install. По умолчанию true.

toml

[install.lockfile]
save = true

Генерировать ли файл блокировки, не являющийся Bun, рядом с bun.lock. (bun.lock всегда будет создан.) В настоящее время "yarn" — единственное поддерживаемое значение.

toml

[install.lockfile]
print = "yarn"

`install.linker`

Настроить стратегию линковщика для установки зависимостей. По умолчанию "isolated" для новых рабочих пространств, "hoisted" для новых проектов с одним пакетом и существующих проектов (сделанных до v1.3.2).

Полную документацию см. в Менеджер пакетов > Изолированные установки.

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

Оболочка для использования при запуске скриптов package.json через bun run или bun. На Windows по умолчанию используется "bun", на других платформах по умолчанию "system".

Чтобы всегда использовать системную оболочку вместо оболочки Bun (поведение по умолчанию, если не Windows):

toml

[run]
# по умолчанию вне Windows
shell = "system"

Чтобы всегда использовать оболочку Bun вместо системной оболочки:

toml

[run]
# по умолчанию на Windows
shell = "bun"

`run.bun` - автоматически псевдоним `node` в `bun`

Когда true, это добавляет в начало $PATH симлинк node, указывающий на бинарник bun для всех скриптов или исполняемых файлов, вызываемых bun run или bun.

Это означает, что если у вас есть скрипт, запускающий node, он фактически запустит bun вместо этого, без необходимости изменять ваш скрипт. Это работает рекурсивно, поэтому если ваш скрипт запускает другой скрипт, запускающий node, он также запустит bun вместо этого. Это применяется и к shebang, поэтому если у вас есть скрипт с shebang, указывающим на node, он фактически запустит bun вместо этого.

По умолчанию это включено, если node ещё нет в вашем $PATH.

toml

[run]
# эквивалентно `bun --bun` для всех команд `bun run`
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"...

Это эквивалентно передаче --silent всем командам bun run:

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` - подавить сообщение о выполняемой команде