bunfig.toml

El comportamiento de Bun se puede configurar usando su archivo de configuración, bunfig.toml.

En general, Bun depende de archivos de configuración preexistentes como package.json y tsconfig.json para configurar su comportamiento. bunfig.toml solo es necesario para configurar cosas específicas de Bun. Este archivo es opcional, y Bun funcionará sin él.

Global vs. local

En general, se recomienda agregar un archivo bunfig.toml a la raíz de tu proyecto, junto con tu package.json.

Para configurar Bun globalmente, también puedes crear un archivo .bunfig.toml en una de las siguientes rutas:

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

Si se detectan tanto un bunfig global como uno local, los resultados se fusionan superficialmente, con el local sobrescribiendo al global. Las banderas de CLI anularán la configuración de bunfig cuando corresponda.

Runtime

El comportamiento del runtime de Bun se configura usando campos de nivel superior en el archivo bunfig.toml.

`preload`

Un array de scripts/plugins para ejecutar antes de ejecutar un archivo o script.

bunfig.toml

toml

# scripts para ejecutar antes de `bun run` de un archivo o script
# registra plugins agregándolos a esta lista
preload = ["./preload.ts"]

`jsx`

Configura cómo Bun maneja JSX. También puedes establecer estos campos en compilerOptions de tu tsconfig.json, pero también se admiten aquí para proyectos que no son de TypeScript.

bunfig.toml

toml

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

Consulta los docs de tsconfig para obtener más información sobre estos campos.

`smol`

Habilita el modo smol. Esto reduce el uso de memoria a costa del rendimiento.

bunfig.toml

toml

# Reduce el uso de memoria a costa del rendimiento
smol = true

`logLevel`

Establece el nivel de registro. Puede ser uno de "debug", "warn" o "error".

bunfig.toml

toml

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

`define`

El campo define te permite reemplazar ciertos identificadores globales con expresiones constantes. Bun reemplazará cualquier uso del identificador con la expresión. La expresión debe ser una cadena JSON.

bunfig.toml

toml

[define]
# Reemplaza cualquier uso de "process.env.bagel" con la cadena `lox`.
# Los valores se analizan como JSON, excepto que las cadenas con comillas simples son compatibles y `'undefined'` se convierte en `undefined` en JS.
# Esto probablemente cambiará en una versión futura a TOML regular en su lugar. Es una reliquia del análisis de argumentos de CLI.
"process.env.bagel" = "'lox'"

`loader`

Configura cómo Bun mapea las extensiones de archivo a los loaders. Esto es útil para cargar archivos que no son compatibles de forma nativa con Bun.

bunfig.toml

toml

[loader]
# cuando se importa un archivo .bagel, trátalo como un archivo tsx
".bagel" = "tsx"

Bun admite los siguientes loaders:

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

`telemetry`

El campo telemetry se usa para habilitar/deshabilitar el análisis. Por defecto, la telemetría está habilitada. Esto es equivalente a la variable de entorno DO_NOT_TRACK.

Actualmente no recopilamos telemetría y esta configuración solo se usa para habilitar/deshabilitar informes de fallos anónimos, pero en el futuro planeamos recopilar información como qué APIs de Bun se usan más o cuánto tiempo tarda bun build.

bunfig.toml

toml

telemetry = false

`console`

Configura el comportamiento de salida de la consola.

`console.depth`

Establece la profundidad predeterminada para la inspección de objetos de console.log(). Predeterminado 2.

bunfig.toml

toml

[console]
depth = 3

Esto controla qué tan profundamente se muestran los objetos anidados en la salida de la consola. Valores más altos muestran más propiedades anidadas pero pueden producir una salida verbosa para objetos complejos. Esta configuración se puede anular con la bandera de CLI --console-depth.

Test runner

El test runner se configura en la sección [test] de tu bunfig.toml.

bunfig.toml

toml

[test]
# la configuración va aquí

`test.root`

El directorio raíz desde el cual ejecutar las pruebas. Predeterminado ..

bunfig.toml

toml

[test]
root = "./__tests__"

`test.preload`

Igual que el campo preload de nivel superior, pero solo se aplica a bun test.

bunfig.toml

toml

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

`test.smol`

Igual que el campo smol de nivel superior, pero solo se aplica a bun test.

bunfig.toml

toml

[test]
smol = true

`test.coverage`

Habilita el informe de cobertura. Predeterminado false. Usa --coverage para anular.

bunfig.toml

toml

[test]
coverage = false

`test.coverageThreshold`

Para especificar un umbral de cobertura. Por defecto, no se establece ningún umbral. Si tu suite de pruebas no alcanza o supera este umbral, bun test saldrá con un código de salida distinto de cero para indicar el fallo.

bunfig.toml

toml

[test]

# para requerir 90% de cobertura a nivel de línea y función
coverageThreshold = 0.9

Se pueden especificar diferentes umbrales para cobertura por línea, por función y por declaración.

bunfig.toml

toml

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

`test.coverageSkipTestFiles`

Si omitir archivos de prueba al calcular estadísticas de cobertura. Predeterminado false.

bunfig.toml

toml

[test]
coverageSkipTestFiles = false

`test.coveragePathIgnorePatterns`

Excluye archivos específicos o patrones de archivos de los informes de cobertura usando patrones glob. Puede ser un patrón de cadena único o un array de patrones.

bunfig.toml

toml

[test]
# Patrón único
coveragePathIgnorePatterns = "**/*.spec.ts"

# Múltiples patrones
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

`test.coverageReporter`

Por defecto, los informes de cobertura se imprimirán en la consola. Para informes de cobertura de código persistentes en entornos CI y para otras herramientas usa lcov.

bunfig.toml

toml

[test]
coverageReporter  = ["text", "lcov"]  # predeterminado ["text"]

`test.coverageDir`

Establece la ruta donde se guardarán los informes de cobertura. Ten en cuenta que esto solo funciona para coverageReporter persistentes como lcov.

bunfig.toml

toml

[test]
coverageDir = "path/to/somewhere"  # predeterminado "coverage"

`test.randomize`

Ejecuta las pruebas en orden aleatorio. Predeterminado false.

bunfig.toml

toml

[test]
randomize = true

Esto ayuda a detectar errores relacionados con interdependencias de pruebas ejecutando las pruebas en un orden diferente cada vez. Cuando se combina con seed, el orden aleatorio se vuelve reproducible.

La bandera de CLI --randomize anulará esta configuración cuando se especifique.

`test.seed`

Establece la semilla aleatoria para la aleatorización de pruebas. Esta opción requiere que randomize sea true.

bunfig.toml

toml

[test]
randomize = true
seed = 2444615283

Usar una semilla hace que el orden de pruebas aleatorizado sea reproducible entre ejecuciones, lo cual es útil para depurar pruebas inestables. Cuando encuentres un fallo de prueba con la aleatorización habilitada, puedes usar la misma semilla para reproducir el orden exacto de las pruebas.

La bandera de CLI --seed anulará esta configuración cuando se especifique.

`test.rerunEach`

Vuelve a ejecutar cada archivo de prueba un número especificado de veces. Predeterminado 0 (ejecutar una vez).

bunfig.toml

toml

[test]
rerunEach = 3

Esto es útil para detectar pruebas inestables o comportamiento no determinista. Cada archivo de prueba se ejecutará el número especificado de veces.

La bandera de CLI --rerun-each anulará esta configuración cuando se especifique.

`test.concurrentTestGlob`

Especifica un patrón glob para ejecutar automáticamente archivos de prueba coincidentes con la ejecución de pruebas concurrentes habilitada. Los archivos de prueba que coincidan con este patrón se comportarán como si se hubiera pasado la bandera --concurrent, ejecutando todas las pruebas dentro de esos archivos concurrentemente.

bunfig.toml

toml

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

Esto es útil para:

Migrar gradualmente suites de pruebas a ejecución concurrente
Ejecutar pruebas de integración concurrentemente mientras se mantienen las pruebas unitarias secuenciales
Separar pruebas concurrentes rápidas de pruebas que requieren ejecución secuencial

La bandera de CLI --concurrent anulará esta configuración cuando se especifique.

`test.onlyFailures`

Cuando está habilitado, solo se muestran las pruebas fallidas en la salida. Esto ayuda a reducir el ruido en suites de pruebas grandes ocultando las pruebas que pasan. Predeterminado false.

bunfig.toml

toml

[test]
onlyFailures = true

Esto es equivalente a usar la bandera --only-failures al ejecutar bun test.

`test.reporter`

Configura la configuración del reportero de pruebas.

`test.reporter.dots`

Habilita el reportero de puntos, que muestra una salida compacta mostrando un punto por cada prueba. Predeterminado false.

bunfig.toml

toml

[test.reporter]
dots = true

`test.reporter.junit`

Habilita el informe XML de JUnit y especifica la ruta del archivo de salida.

bunfig.toml

toml

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

Esto genera un informe XML de JUnit que puede ser consumido por sistemas CI y otras herramientas.

Package manager

La gestión de paquetes es un tema complejo; para admitir una gama de casos de uso, el comportamiento de bun install se puede configurar en la sección [install].

bunfig.toml

toml

[install]
# la configuración va aquí

`install.optional`

Si instalar dependencias opcionales. Predeterminado true.

bunfig.toml

toml

[install]
optional = true

`install.dev`

Si instalar dependencias de desarrollo. Predeterminado true.

bunfig.toml

toml

[install]
dev = true

`install.peer`

Si instalar dependencias peer. Predeterminado true.

bunfig.toml

toml

[install]
peer = true

`install.production`

Si bun install se ejecutará en "modo producción". Predeterminado false.

En modo producción, no se instalan "devDependencies". Puedes usar --production en la CLI para anular esta configuración.

bunfig.toml

toml

[install]
production = false

`install.exact`

Si establecer una versión exacta en package.json. Predeterminado false.

Por defecto, Bun usa rangos caret; si la versión latest de un paquete es 2.4.1, el rango de versiones en tu package.json será ^2.4.1. Esto indica que cualquier versión desde 2.4.1 hasta (pero sin incluir) 3.0.0 es aceptable.

bunfig.toml

toml

[install]
exact = false

`install.saveTextLockfile`

Si es false, genera un bun.lockb binario en lugar de un archivo bun.lock basado en texto al ejecutar bun install y no hay ningún lockfile presente.

Predeterminado true (desde Bun v1.2).

bunfig.toml

toml

[install]
saveTextLockfile = false

`install.auto`

Para configurar el comportamiento de auto-instalación de paquetes de Bun. Predeterminado "auto" — cuando no se encuentra una carpeta node_modules, Bun instalará automáticamente las dependencias sobre la marcha durante la ejecución.

bunfig.toml

toml

[install]
auto = "auto"

Los valores válidos son:

Valor	Descripción
`"auto"`	Resuelve módulos desde `node_modules` local si existe. De lo contrario, auto-instala dependencias sobre la marcha.
`"force"`	Siempre auto-instala dependencias, incluso si `node_modules` existe.
`"disable"`	Nunca auto-instala dependencias.
`"fallback"`	Verifica `node_modules` local primero, luego auto-instala cualquier paquete que no se encuentre. Puedes habilitar esto desde la CLI con `bun -i`.

`install.frozenLockfile`

Cuando es true, bun install no actualizará bun.lock. Predeterminado false. Si package.json y el bun.lock existente no están de acuerdo, esto generará un error.

bunfig.toml

toml

[install]
frozenLockfile = false

`install.dryRun`

Si bun install realmente instalará dependencias. Predeterminado false. Cuando es true, es equivalente a establecer --dry-run en todos los comandos bun install.

bunfig.toml

toml

[install]
dryRun = false

`install.globalDir`

Para configurar el directorio donde Bun coloca los paquetes instalados globalmente.

Variable de entorno: BUN_INSTALL_GLOBAL_DIR

bunfig.toml

toml

[install]
# donde `bun install --global` instala paquetes
globalDir = "~/.bun/install/global"

`install.globalBinDir`

Para configurar el directorio donde Bun instala binarios y CLIs instalados globalmente.

Variable de entorno: BUN_INSTALL_BIN

bunfig.toml

toml

[install]
# donde se enlazan los bins de paquetes instalados globalmente
globalBinDir = "~/.bun/bin"

`install.registry`

El registro predeterminado es https://registry.npmjs.org/. Esto se puede configurar globalmente en bunfig.toml:

bunfig.toml

toml

[install]
# establece el registro predeterminado como una cadena
registry = "https://registry.npmjs.org"
# establece un token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# establece un nombre de usuario/contraseña
registry = "https://username:password@registry.npmjs.org"

`install.linkWorkspacePackages`

Para configurar cómo se enlazan los paquetes del espacio de trabajo, usa la opción install.linkWorkspacePackages.

Si enlazar paquetes del espacio de trabajo desde la raíz del monorepo a sus respectivos directorios node_modules. Predeterminado true.

bunfig.toml

toml

[install]
linkWorkspacePackages = true

`install.scopes`

Para configurar un registro para un scope particular (por ejemplo, @myorg/<package>) usa install.scopes. Puedes hacer referencia a variables de entorno con la notación $variable.

bunfig.toml

toml

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

# registro con nombre de usuario/contraseña
# puedes hacer referencia a variables de entorno
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

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

`install.ca` y `install.cafile`

Para configurar un certificado CA, usa install.ca o install.cafile para especificar una ruta a un archivo de certificado CA.

bunfig.toml

toml

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

# Una ruta a un archivo de certificado CA. El archivo puede contener múltiples certificados.
cafile = "path/to/cafile"

`install.cache`

Para configurar el comportamiento de la caché:

bunfig.toml

toml

[install.cache]

# el directorio a usar para la caché
dir = "~/.bun/install/cache"

# cuando es true, no cargar desde la caché global.
# Bun aún puede escribir en node_modules/.cache
disable = false

# cuando es true, siempre resolver las últimas versiones desde el registro
disableManifest = false

`install.lockfile`

Para configurar el comportamiento del lockfile, usa la sección install.lockfile.

Si generar un lockfile en bun install. Predeterminado true.

bunfig.toml

toml

[install.lockfile]
save = true

Si generar un lockfile que no sea de Bun junto con bun.lock. (Siempre se creará un bun.lock.) Actualmente "yarn" es el único valor admitido.

bunfig.toml

toml

[install.lockfile]
print = "yarn"

`install.linker`

Configura la estrategia de linker para instalar dependencias. Predeterminado "isolated" para nuevos espacios de trabajo, "hoisted" para nuevos proyectos de un solo paquete y proyectos existentes (creados pre-v1.3.2).

Para documentación completa consulta Package manager > Isolated installs.

bunfig.toml

toml

[install]
linker = "hoisted"

Los valores válidos son:

Valor	Descripción
`"hoisted"`	Enlaza dependencias en un directorio `node_modules` compartido.
`"isolated"`	Enlaza dependencias dentro de cada instalación de paquete.

bunfig.toml

toml

[debug]
# Al navegar a un enlace blob: o src:, abre el archivo en tu editor
# Si no, intenta con $EDITOR o $VISUAL
# Si eso aún falla, intentará Visual Studio Code, luego Sublime Text, luego algunos otros
# Esto es 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`

Configura un escáner de seguridad para escanear paquetes en busca de vulnerabilidades antes de la instalación.

Primero, instala un escáner de seguridad desde npm:

bash

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

Luego configúralo en tu bunfig.toml:

toml

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

Cuando se configura un escáner de seguridad:

La auto-instalación se deshabilita automáticamente por seguridad
Los paquetes se escanean antes de la instalación
La instalación se cancela si se encuentran problemas fatales
Se muestran advertencias de seguridad durante la instalación

Obtén más información sobre usar y escribir escáneres de seguridad.

`install.minimumReleaseAge`

Configura una edad mínima (en segundos) para versiones de paquetes npm. Las versiones de paquetes publicadas más recientemente que este umbral se filtrarán durante la instalación. El predeterminado es null (deshabilitado).

bunfig.toml

toml

[install]
# Solo instala versiones de paquetes publicadas hace al menos 3 días
minimumReleaseAge = 259200
# Estos paquetes omitirán el requisito de edad mínima de 3 días
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

Para más detalles consulta Edad mínima de lanzamiento en la documentación de install.

`bun run`

El comando bun run se puede configurar en la sección [run]. Esto se aplica al comando bun run y al comando bun al ejecutar un archivo o ejecutable o script.

Actualmente, bunfig.toml solo se carga automáticamente para bun run en un proyecto local (no busca un .bunfig.toml global).

`run.shell` - usa la shell del sistema o la shell de Bun

La shell a usar al ejecutar scripts de package.json mediante bun run o bun. En Windows, el predeterminado es "bun" y en otras plataformas el predeterminado es "system".

Para usar siempre la shell del sistema en lugar de la shell de Bun (comportamiento predeterminado a menos que sea Windows):

bunfig.toml

toml

[run]
# predeterminado fuera de Windows
shell = "system"

Para usar siempre la shell de Bun en lugar de la shell del sistema:

bunfig.toml

toml

[run]
# predeterminado en Windows
shell = "bun"

`run.bun` - auto alias `node` a `bun`

Cuando es true, esto antepone $PATH con un symlink node que apunta al binario bun para todos los scripts o ejecutables invocados por bun run o bun.

Esto significa que si tienes un script que ejecuta node, en realidad ejecutará bun en su lugar, sin necesidad de cambiar tu script. Esto funciona recursivamente, por lo que si tu script ejecuta otro script que ejecuta node, también ejecutará bun en su lugar. Esto se aplica también a los shebangs, por lo que si tienes un script con un shebang que apunta a node, en realidad ejecutará bun en su lugar.

Por defecto, esto está habilitado si node no está ya en tu $PATH.

bunfig.toml

toml

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

Puedes probar esto ejecutando:

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

Esta opción es equivalente a anteponer --bun a todos los comandos bun run:

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

Si se establece en false, esto deshabilitará el symlink node.

`run.silent` - suprime informar el comando que se está ejecutando

Cuando es true, suprime la salida del comando que se está ejecutando por bun run o bun.

bunfig.toml

toml

[run]
silent = true

Sin esta opción, el comando que se está ejecutando se imprimirá en la consola:

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

txt

Running "dev"...

Con esta opción, el comando que se está ejecutando no se imprimirá en la consola:

bun run dev

txt

Running "dev"...

Esto es equivalente a pasar --silent a todos los comandos bun run:

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

Global vs. local ​

Runtime ​

preload ​

jsx ​

smol ​

logLevel ​

define ​

loader ​

telemetry ​

console ​

console.depth ​

Test runner ​

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 ​

Package manager ​

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 y install.cafile ​

install.cache ​

install.lockfile ​

install.linker ​

install.security.scanner ​

install.minimumReleaseAge ​

bun run ​

run.shell - usa la shell del sistema o la shell de Bun ​

run.bun - auto alias node a bun ​

run.silent - suprime informar el comando que se está ejecutando ​

Global vs. local

Runtime

`preload`

`jsx`

`smol`

`logLevel`

`define`

`loader`

`telemetry`

`console`

`console.depth`

Test runner

`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`

Package manager

`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` y `install.cafile`

`install.cache`

`install.lockfile`

`install.linker`

`install.security.scanner`

`install.minimumReleaseAge`

`bun run`

`run.shell` - usa la shell del sistema o la shell de Bun

`run.bun` - auto alias `node` a `bun`

`run.silent` - suprime informar el comando que se está ejecutando