Поведение 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

Массив скриптов/плагинов для выполнения перед запуском файла или скрипта.

bunfig.toml

# скрипты для запуска перед `bun run` файла или скрипта
# зарегистрировать плагины, добавив их в этот список
preload = ["./preload.ts"]

jsx

Настройте, как Bun обрабатывает JSX. Вы также можете установить эти поля в compilerOptions вашего tsconfig.json, но они также поддерживаются здесь для проектов, не использующих TypeScript.

bunfig.toml

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

Дополнительную информацию об этих полях см. в документации tsconfig.

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol

Включить режим smol. Это уменьшает использование памяти ценой производительности.

bunfig.toml

# Уменьшить использование памяти ценой производительности
smol = true

logLevel

Установить уровень логирования. Это может быть одно из значений "debug", "warn" или "error".

bunfig.toml

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

define

Поле define позволяет заменять некоторые глобальные идентификаторы постоянными выражениями. Bun заменит любое использование идентификатора выражением. Выражение должно быть JSON-строкой.

bunfig.toml

[define]
# Заменить любое использование "process.env.bagel" на строку `lox`.
# Значения анализируются как JSON, за исключением того, что поддерживаются строки в одинарных кавычках, и `'undefined'` становится `undefined` в JS.
# Вероятно, в будущем выпуске это изменится на обычный TOML. Это наследие от разбора аргументов CLI.
"process.env.bagel" = "'lox'"

loader

Настройте, как Bun сопоставляет расширения файлов с загрузчиками. Это полезно для загрузки файлов, которые не поддерживаются Bun нативно.

bunfig.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.

bunfig.toml

telemetry = false

console

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

console.depth

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

bunfig.toml

[console]
depth = 3

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

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

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

bunfig.toml

[test]
# конфигурация здесь

test.root

Корневой каталог для запуска тестов. По умолчанию ..

bunfig.toml

[test]
root = "./__tests__"

test.preload

То же, что и поле preload верхнего уровня, но применяется только к bun test.

bunfig.toml

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

test.smol

То же, что и поле smol верхнего уровня, но применяется только к bun test.

bunfig.toml

[test]
smol = true

test.coverage

Включает отчёт о покрытии. По умолчанию false. Используйте --coverage для переопределения.

bunfig.toml

[test]
coverage = false

test.coverageThreshold

Для указания порога покрытия. По умолчанию порог не установлен. Если ваш набор тестов не достигает или не превышает этот порог, bun test завершится с ненулевым кодом выхода, указывающим на неудачу.

bunfig.toml

[test]

# требовать 90% покрытия на уровне строк и функций
coverageThreshold = 0.9

Различные пороги могут быть указаны для покрытия по строкам, функциям и утверждениям.

bunfig.toml

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

test.coverageSkipTestFiles

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

bunfig.toml

[test]
coverageSkipTestFiles = false

test.coveragePathIgnorePatterns

Исключить определённые файлы или шаблоны файлов из отчётов о покрытии с использованием шаблонов glob. Может быть одной строкой шаблона или массивом шаблонов.

bunfig.toml

[test]
# Один шаблон
coveragePathIgnorePatterns = "**/*.spec.ts"

# Несколько шаблонов
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

test.coverageReporter

По умолчанию отчёты о покрытии будут выводиться в консоль. Для постоянных отчётов о покрытии кода в средах CI и для других инструментов используйте lcov.

bunfig.toml

[test]
coverageReporter  = ["text", "lcov"]  # по умолчанию ["text"]

test.coverageDir

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

bunfig.toml

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

test.randomize

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

bunfig.toml

[test]
randomize = true

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

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

test.seed

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

bunfig.toml

[test]
randomize = true
seed = 2444615283

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

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

test.rerunEach

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

bunfig.toml

[test]
rerunEach = 3

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

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

test.concurrentTestGlob

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

bunfig.toml

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

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

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

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

test.onlyFailures

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

bunfig.toml

[test]
onlyFailures = true

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

test.reporter

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

test.reporter.dots

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

bunfig.toml

[test.reporter]
dots = true

test.reporter.junit

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

bunfig.toml

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

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

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

Управление пакетами — сложная задача; для поддержки ряда случаев использования поведение bun install может быть настроено в разделе [install].

bunfig.toml

[install]
# конфигурация здесь

install.optional

Устанавливать ли опциональные зависимости. По умолчанию true.

bunfig.toml

[install]
optional = true

install.dev

Устанавливать ли зависимости для разработки. По умолчанию true.

bunfig.toml

[install]
dev = true

install.peer

Устанавливать ли пир-зависимости. По умолчанию true.

bunfig.toml

[install]
peer = true

install.production

Будет ли bun install работать в «режиме продакшена». По умолчанию false.

В режиме продакшена "devDependencies" не устанавливаются. Вы можете использовать --production в CLI для переопределения этой настройки.

bunfig.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 приемлема.

bunfig.toml

[install]
exact = false

install.saveTextLockfile

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

По умолчанию true (с Bun v1.2).

bunfig.toml

[install]
saveTextLockfile = false

install.auto

Для настройки поведения автоматической установки пакетов Bun. По умолчанию "auto" — когда папка node_modules не найдена, Bun автоматически установит зависимости на лету во время выполнения.

bunfig.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 не согласованы, это вызовет ошибку.

bunfig.toml

[install]
frozenLockfile = false

install.dryRun

Будет ли bun install фактически устанавливать зависимости. По умолчанию false. Когда true, это эквивалентно установке --dry-run для всех команд bun install.

bunfig.toml

[install]
dryRun = false

install.globalDir

Для настройки каталога, куда Bun помещает глобально установленные пакеты.

Переменная окружения: BUN_INSTALL_GLOBAL_DIR

bunfig.toml

[install]
# где `bun install --global` устанавливает пакеты
globalDir = "~/.bun/install/global"

install.globalBinDir

Для настройки каталога, куда Bun устанавливает глобально установленные бинарники и CLI.

Переменная окружения: BUN_INSTALL_BIN

bunfig.toml

[install]
# куда линкуются бинарники глобально установленных пакетов
globalBinDir = "~/.bun/bin"

install.registry

Реестр по умолчанию — https://registry.npmjs.org/. Это может быть глобально настроено в bunfig.toml:

bunfig.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.

bunfig.toml

[install]
linkWorkspacePackages = true

install.scopes

Для настройки реестра для определённой области (например, @myorg/<package>) используйте install.scopes. Вы можете ссылаться на переменные окружения с помощью нотации $variable.

bunfig.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-сертификата.

bunfig.toml

[install]
# CA-сертификат как строка
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# Путь к файлу CA-сертификата. Файл может содержать несколько сертификатов.
cafile = "path/to/cafile"

install.cache

Для настройки поведения кэша:

bunfig.toml

[install.cache]

# каталог для использования кэша
dir = "~/.bun/install/cache"

# когда true, не загружать из глобального кэша.
# Bun всё ещё может записывать в node_modules/.cache
disable = false

# когда true, всегда разрешать последние версии из реестра
disableManifest = false

install.lockfile

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

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

bunfig.toml

[install.lockfile]
save = true

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

bunfig.toml

[install.lockfile]
print = "yarn"

install.linker

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

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

bunfig.toml

[install]
linker = "hoisted"

Допустимые значения:

Значение	Описание
"hoisted"	Связывать зависимости в общем каталоге node_modules.
"isolated"	Связывать зависимости внутри каждой установки пакета.

bunfig.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:

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

Затем настройте его в вашем bunfig.toml:

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

Когда сканер безопасности настроен:

• Автоматическая установка автоматически отключается для безопасности
• Пакеты сканируются перед установкой
• Установка отменяется, если найдены фатальные проблемы
• Предупреждения о безопасности отображаются во время установки

Узнайте больше об использовании и написании сканеров безопасности.

install.minimumReleaseAge

Настроить минимальный возраст (в секундах) для версий пакетов npm. Версии пакетов, опубликованные более недавно, чем этот порог, будут отфильтрованы во время установки. По умолчанию null (отключено).

bunfig.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):

bunfig.toml

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

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

bunfig.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.

bunfig.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.

bunfig.toml

[run]
silent = true

Без этой опции выполняемая команда будет напечатана в консоль:

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

Running "dev"...

С этой опцией выполняемая команда не будет напечатана в консоль:

bun run dev

Running "dev"...

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

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