O comportamento do Bun pode ser configurado usando seu arquivo de configuração, bunfig.toml.

Em geral, o Bun depende de arquivos de configuração pré-existentes como package.json e tsconfig.json para configurar seu comportamento. bunfig.toml é necessário apenas para configurar coisas específicas do Bun. Este arquivo é opcional, e o Bun funcionará sem ele.

Global vs. local

Em geral, é recomendado adicionar um arquivo bunfig.toml na raiz do seu projeto, junto com seu package.json.

Para configurar o Bun globalmente, você também pode criar um arquivo .bunfig.toml em um dos seguintes caminhos:

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

Se ambos os bunfig global e local forem detectados, os resultados são mesclados superficialmente, com o local sobrescrevendo o global. Flags de CLI substituirão a configuração bunfig quando aplicável.

Runtime

O comportamento do runtime do Bun é configurado usando campos de nível superior no arquivo bunfig.toml.

preload

Um array de scripts/plugins para executar antes de rodar um arquivo ou script.

bunfig.toml

# scripts para executar antes de `bun run` de um arquivo ou script
# registra plugins adicionando-os a esta lista
preload = ["./preload.ts"]

jsx

Configure como o Bun lida com JSX. Você também pode definir estes campos no compilerOptions do seu tsconfig.json, mas eles são suportados aqui também para projetos não-TypeScript.

bunfig.toml

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

Consulte a documentação tsconfig para mais informações sobre estes campos.

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol

Ativa o modo smol. Isso reduz o uso de memória com custo para o desempenho.

bunfig.toml

# Reduz o uso de memória com custo para o desempenho
smol = true

logLevel

Define o nível de log. Pode ser um de "debug", "warn" ou "error".

bunfig.toml

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

define

O campo define permite substituir certos identificadores globais por expressões constantes. O Bun substituirá qualquer uso do identificador pela expressão. A expressão deve ser uma string JSON.

bunfig.toml

[define]
# Substitui qualquer uso de "process.env.bagel" pela string `lox`.
# Os valores são analisados como JSON, exceto que strings com aspas simples são suportadas e `'undefined'` se torna `undefined` em JS.
# Isso provavelmente mudará em uma versão futura para ser TOML regular. É uma herança do parsing de argumentos CLI.
"process.env.bagel" = "'lox'"

loader

Configure como o Bun mapeia extensões de arquivo para loaders. Isso é útil para carregar arquivos que não são suportados nativamente pelo Bun.

bunfig.toml

[loader]
# quando um arquivo .bagel é importado, trata como um arquivo tsx
".bagel" = "tsx"

O Bun suporta os seguintes loaders:

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

telemetry

O campo telemetry é usado para ativar/desativar analytics. Por padrão, telemetry está ativado. Isso é equivalente à variável de ambiente DO_NOT_TRACK.

Atualmente não coletamos telemetry e esta configuração é usada apenas para ativar/desativar relatórios de crash anônimos, mas no futuro planejamos coletar informações como quais APIs do Bun são mais usadas ou quanto tempo bun build leva.

bunfig.toml

telemetry = false

console

Configure o comportamento de saída do console.

console.depth

Define a profundidade padrão para inspeção de objetos do console.log(). Padrão 2.

bunfig.toml

[console]
depth = 3

Isso controla quão profundamente os objetos aninhados são exibidos na saída do console. Valores mais altos mostram mais propriedades aninhadas, mas podem produzir saída verbosa para objetos complexos. Esta configuração pode ser substituída pela flag CLI --console-depth.

Test runner

O test runner é configurado na seção [test] do seu bunfig.toml.

bunfig.toml

[test]
# configuração aqui

test.root

O diretório raiz para executar testes. Padrão ..

bunfig.toml

[test]
root = "./__tests__"

test.preload

Mesmo que o campo preload de nível superior, mas aplica-se apenas a bun test.

bunfig.toml

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

test.smol

Mesmo que o campo smol de nível superior, mas aplica-se apenas a bun test.

bunfig.toml

[test]
smol = true

test.coverage

Ativa relatórios de coverage. Padrão false. Use --coverage para substituir.

bunfig.toml

[test]
coverage = false

test.coverageThreshold

Para especificar um threshold de coverage. Por padrão, nenhum threshold é definido. Se sua suíte de testes não atingir ou exceder este threshold, bun test sairá com um código de saída não zero para indicar falha.

bunfig.toml

[test]

# para exigir 90% de coverage de linha e função
coverageThreshold = 0.9

Diferentes thresholds podem ser especificados para coverage por linha, por função e por statement.

bunfig.toml

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

test.coverageSkipTestFiles

Se deve pular arquivos de teste ao computar estatísticas de coverage. Padrão false.

bunfig.toml

[test]
coverageSkipTestFiles = false

test.coveragePathIgnorePatterns

Exclui arquivos específicos ou padrões de arquivo de relatórios de coverage usando padrões glob. Pode ser um padrão de string única ou um array de padrões.

bunfig.toml

[test]
# padrão único
coveragePathIgnorePatterns = "**/*.spec.ts"

# múltiplos padrões
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

test.coverageReporter

Por padrão, relatórios de coverage serão impressos no console. Para relatórios de coverage persistentes em ambientes CI e para outras ferramentas use lcov.

bunfig.toml

[test]
coverageReporter  = ["text", "lcov"]  # padrão ["text"]

test.coverageDir

Define o caminho onde relatórios de coverage serão salvos. Note que isso funciona apenas para coverageReporter persistente como lcov.

bunfig.toml

[test]
coverageDir = "path/to/somewhere"  # padrão "coverage"

test.randomize

Executa testes em ordem aleatória. Padrão false.

bunfig.toml

[test]
randomize = true

Isso ajuda a capturar bugs relacionados a interdependências de testes executando testes em uma ordem diferente a cada vez. Quando combinado com seed, a ordem aleatória se torna reprodutível.

A flag CLI --randomize substituirá esta configuração quando especificada.

test.seed

Define a seed aleatória para randomização de testes. Esta opção requer que randomize seja true.

bunfig.toml

[test]
randomize = true
seed = 2444615283

Usar uma seed torna a ordem de testes randomizada reprodutível entre execuções, o que é útil para debugar testes flaky. Quando você encontrar uma falha de teste com randomização ativada, pode usar a mesma seed para reproduzir a ordem exata dos testes.

A flag CLI --seed substituirá esta configuração quando especificada.

test.rerunEach

Re-executa cada arquivo de teste um número especificado de vezes. Padrão 0 (executa uma vez).

bunfig.toml

[test]
rerunEach = 3

Isso é útil para capturar testes flaky ou comportamento não determinístico. Cada arquivo de teste será executado o número especificado de vezes.

A flag CLI --rerun-each substituirá esta configuração quando especificada.

test.concurrentTestGlob

Especifica um padrão glob para executar automaticamente arquivos de teste correspondentes com execução de teste concorrente ativada. Arquivos de teste que correspondem a este padrão se comportarão como se a flag --concurrent fosse passada, executando todos os testes dentro desses arquivos concorrentemente.

bunfig.toml

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

Isso é útil para:

• Migrar gradualmente suítes de teste para execução concorrente
• Executar testes de integração concorrentemente enquanto mantém testes unitários sequenciais
• Separar testes concorrentes rápidos de testes que requerem execução sequencial

A flag CLI --concurrent substituirá esta configuração quando especificada.

test.onlyFailures

Quando ativado, apenas testes com falha são exibidos na saída. Isso ajuda a reduzir ruído em grandes suítes de teste ocultando testes que passaram. Padrão false.

bunfig.toml

[test]
onlyFailures = true

Isso é equivalente a usar a flag --only-failures ao executar bun test.

test.reporter

Configure as configurações do reportador de testes.

test.reporter.dots

Ativa o reportador dots, que exibe uma saída compacta mostrando um ponto para cada teste. Padrão false.

bunfig.toml

[test.reporter]
dots = true

test.reporter.junit

Ativa relatórios JUnit XML e especifica o caminho do arquivo de saída.

bunfig.toml

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

Isso gera um relatório JUnit XML que pode ser consumido por sistemas CI e outras ferramentas.

Package manager

Gerenciamento de pacotes é uma questão complexa; para suportar uma gama de casos de uso, o comportamento de bun install pode ser configurado na seção [install].

bunfig.toml

[install]
# configuração aqui

install.optional

Se deve instalar dependências opcionais. Padrão true.

bunfig.toml

[install]
optional = true

install.dev

Se deve instalar dependências de desenvolvimento. Padrão true.

bunfig.toml

[install]
dev = true

install.peer

Se deve instalar dependências peer. Padrão true.

bunfig.toml

[install]
peer = true

install.production

Se bun install executará em "modo de produção". Padrão false.

No modo de produção, "devDependencies" não são instaladas. Você pode usar --production na CLI para substituir esta configuração.

bunfig.toml

[install]
production = false

install.exact

Se deve definir uma versão exata no package.json. Padrão false.

Por padrão, o Bun usa intervalos caret; se a versão latest de um pacote é 2.4.1, o intervalo de versão no seu package.json será ^2.4.1. Isso indica que qualquer versão de 2.4.1 até (mas não incluindo) 3.0.0 é aceitável.

bunfig.toml

[install]
exact = false

install.saveTextLockfile

Se false, gera um bun.lockb binário em vez de um arquivo bun.lock baseado em texto ao executar bun install e nenhum lockfile está presente.

Padrão true (desde Bun v1.2).

bunfig.toml

[install]
saveTextLockfile = false

install.auto

Para configurar o comportamento de auto-instalação de pacotes do Bun. Padrão "auto" — quando nenhuma pasta node_modules é encontrada, o Bun instalará automaticamente dependências em tempo de execução durante a execução.

bunfig.toml

[install]
auto = "auto"

Valores válidos são:

Valor	Descrição
"auto"	Resolve módulos do node_modules local se existir. Caso contrário, auto-instala dependências em tempo de execução.
"force"	Sempre auto-instala dependências, mesmo se node_modules existir.
"disable"	Nunca auto-instala dependências.
"fallback"	Verifica node_modules local primeiro, depois auto-instala quaisquer pacotes que não forem encontrados. Você pode ativar isso na CLI com bun -i.

install.frozenLockfile

Quando true, bun install não atualizará bun.lock. Padrão false. Se package.json e o bun.lock existente não estiverem de acordo, isso gerará erro.

bunfig.toml

[install]
frozenLockfile = false

install.dryRun

Se bun install realmente instalará dependências. Padrão false. Quando true, é equivalente a definir --dry-run em todos os comandos bun install.

bunfig.toml

[install]
dryRun = false

install.globalDir

Para configurar o diretório onde o Bun coloca pacotes instalados globalmente.

Variável de ambiente: BUN_INSTALL_GLOBAL_DIR

bunfig.toml

[install]
# onde `bun install --global` instala pacotes
globalDir = "~/.bun/install/global"

install.globalBinDir

Para configurar o diretório onde o Bun instala binários e CLIs instalados globalmente.

Variável de ambiente: BUN_INSTALL_BIN

bunfig.toml

[install]
# onde bins de pacotes instalados globalmente são linkados
globalBinDir = "~/.bun/bin"

install.registry

O registry padrão é https://registry.npmjs.org/. Isso pode ser configurado globalmente em bunfig.toml:

bunfig.toml

[install]
# define registry padrão como string
registry = "https://registry.npmjs.org"
# define um token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# define um nome de usuário/senha
registry = "https://username:password@registry.npmjs.org"

install.linkWorkspacePackages

Para configurar como pacotes de workspace são linkados, use a opção install.linkWorkspacePackages.

Se deve linkar pacotes de workspace da raiz do monorepo para seus respectivos diretórios node_modules. Padrão true.

bunfig.toml

[install]
linkWorkspacePackages = true

install.scopes

Para configurar um registry para um escopo específico (ex: @myorg/<package>) use install.scopes. Você pode referenciar variáveis de ambiente com a notação $variable.

bunfig.toml

[install.scopes]
# registry como string
myorg = "https://username:password@registry.myorg.com/"

# registry com nome de usuário/senha
# você pode referenciar variáveis de ambiente
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

# registry com token
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }

install.ca e install.cafile

Para configurar um certificado CA, use install.ca ou install.cafile para especificar um caminho para um arquivo de certificado CA.

bunfig.toml

[install]
# O certificado CA como string
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# Um caminho para um arquivo de certificado CA. O arquivo pode conter múltiplos certificados.
cafile = "path/to/cafile"

install.cache

Para configurar o comportamento do cache:

bunfig.toml

[install.cache]

# o diretório para usar para o cache
dir = "~/.bun/install/cache"

# quando true, não carrega do cache global.
# Bun ainda pode escrever em node_modules/.cache
disable = false

# quando true, sempre resolve as últimas versões do registry
disableManifest = false

install.lockfile

Para configurar comportamento de lockfile, use a seção install.lockfile.

Se deve gerar um lockfile em bun install. Padrão true.

bunfig.toml

[install.lockfile]
save = true

Se deve gerar um lockfile não-Bun junto com bun.lock. (Um bun.lock sempre será criado.) Atualmente "yarn" é o único valor suportado.

bunfig.toml

[install.lockfile]
print = "yarn"

install.linker

Configure a estratégia de linker para instalar dependências. Padrão "isolated" para novos workspaces, "hoisted" para novos projetos de pacote único e projetos existentes (feitos pré-v1.3.2).

Para documentação completa consulte Package manager > Isolated installs.

bunfig.toml

[install]
linker = "hoisted"

Valores válidos são:

Valor	Descrição
"hoisted"	Linka dependências em um diretório node_modules compartilhado.
"isolated"	Linka dependências dentro de cada instalação de pacote.

bunfig.toml

[debug]
# Ao navegar para um link blob: ou src:, abre o arquivo no seu editor
# Se não, tenta $EDITOR ou $VISUAL
# Se ainda falhar, tenta Visual Studio Code, depois Sublime Text, depois alguns outros
# Isso é usado por Bun.openInEditor()
editor = "code"

# Lista de editores:
# - "subl", "sublime"
# - "vscode", "code"
# - "textmate", "mate"
# - "idea"
# - "webstorm"
# - "nvim", "neovim"
# - "vim","vi"
# - "emacs"

install.security.scanner

Configure um scanner de segurança para escanear pacotes por vulnerabilidades antes da instalação.

Primeiro, instale um scanner de segurança do npm:

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

Depois configure-o no seu bunfig.toml:

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

Quando um scanner de segurança é configurado:

• Auto-instalação é automaticamente desativada por segurança
• Pacotes são escaneados antes da instalação
• Instalação é cancelada se problemas fatais forem encontrados
• Avisos de segurança são exibidos durante a instalação

Saiba mais sobre usando e escrevendo security scanners.

install.minimumReleaseAge

Configure uma idade mínima (em segundos) para versões de pacotes npm. Versões de pacotes publicadas mais recentemente que este threshold serão filtradas durante a instalação. Padrão é null (desativado).

bunfig.toml

[install]
# Instala apenas versões de pacotes publicadas há pelo menos 3 dias
minimumReleaseAge = 259200
# Estes pacotes ignorarão o requisito mínimo de idade de 3 dias
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

Para mais detalhes veja Minimum release age na documentação de install.

bun run

O comando bun run pode ser configurado na seção [run]. Isso se aplica ao comando bun run e ao comando bun ao executar um arquivo ou executável ou script.

Atualmente, bunfig.toml é carregado automaticamente apenas para bun run em um projeto local (não verifica por um .bunfig.toml global).

run.shell - usa o shell do sistema ou o shell do Bun

O shell para usar ao executar scripts package.json via bun run ou bun. No Windows, o padrão é "bun" e em outras plataformas o padrão é "system".

Para sempre usar o shell do sistema em vez do shell do Bun (comportamento padrão a menos que Windows):

bunfig.toml

[run]
# padrão fora do Windows
shell = "system"

Para sempre usar o shell do Bun em vez do shell do sistema:

bunfig.toml

[run]
# padrão no Windows
shell = "bun"

run.bun - auto alias node para bun

Quando true, isso prepende $PATH com um symlink node que aponta para o binário bun para todos os scripts ou executáveis invocados por bun run ou bun.

Isso significa que se você tiver um script que executa node, ele executará bun em vez disso, sem precisar mudar seu script. Isso funciona recursivamente, então se seu script executa outro script que executa node, ele também executará bun em vez disso. Isso se aplica a shebangs também, então se você tiver um script com um shebang que aponta para node, ele executará bun em vez disso.

Por padrão, isso está ativado se node não estiver no seu $PATH.

bunfig.toml

[run]
# equivalente a `bun --bun` para todos os comandos `bun run`
bun = true

Você pode testar isso executando:

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

Esta opção é equivalente a prefixar todos os comandos bun run com --bun:

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

Se definido como false, isso desativará o symlink node.

run.silent - suprime reportar o comando sendo executado

Quando true, suprime a saída do comando sendo executado por bun run ou bun.

bunfig.toml

[run]
silent = true

Sem esta opção, o comando sendo executado será impresso no console:

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

Running "dev"...

Com esta opção, o comando sendo executado não será impresso no console:

bun run dev

Running "dev"...

Isso é equivalente a passar --silent para todos os comandos bun run:

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