Il comportamento di Bun può essere configurato usando il suo file di configurazione, bunfig.toml.

In generale, Bun si basa su file di configurazione preesistenti come package.json e tsconfig.json per configurare il suo comportamento. bunfig.toml è necessario solo per configurare cose specifiche di Bun. Questo file è opzionale e Bun funzionerà senza di esso.

Globale vs locale

In generale, si raccomanda di aggiungere un file bunfig.toml alla root del tuo progetto, insieme al tuo package.json.

Per configurare Bun globalmente, puoi anche creare un file .bunfig.toml in uno dei seguenti percorsi:

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

Se vengono rilevati sia un bunfig globale che uno locale, i risultati vengono uniti superficialmente, con quello locale che sovrascrive quello globale. I flag CLI sovrascriveranno le impostazioni bunfig dove applicabile.

Runtime

Il comportamento del runtime di Bun è configurato usando campi di primo livello nel file bunfig.toml.

preload

Un array di script/plugin da eseguire prima di eseguire un file o script.

bunfig.toml

# script da eseguire prima di `bun run` di un file o script
# registra plugin aggiungendoli a questa lista
preload = ["./preload.ts"]

jsx

Configura come Bun gestisce JSX. Puoi anche impostare questi campi in compilerOptions del tuo tsconfig.json, ma sono supportati anche qui per progetti non-TypeScript.

bunfig.toml

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

Fai riferimento ai docs tsconfig per maggiori informazioni su questi campi.

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol

Abilita la modalità smol. Questo riduce l'uso di memoria a scapito delle prestazioni.

bunfig.toml

# Riduci l'uso di memoria a scapito delle prestazioni
smol = true

logLevel

Imposta il livello di log. Questo può essere uno tra "debug", "warn" o "error".

bunfig.toml

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

define

Il campo define permette di sostituire alcuni identificatori globali con espressioni costanti. Bun sostituirà ogni uso dell'identificatore con l'espressione. L'espressione dovrebbe essere una stringa JSON.

bunfig.toml

[define]
# Sostituisci ogni uso di "process.env.bagel" con la stringa `lox`.
# I valori sono parsati come JSON, eccetto le stringhe con apici singoli sono supportate e `'undefined'` diventa `undefined` in JS.
# Questo probabilmente cambierà in una release futura per essere solo TOML regolare invece. È un residuo dal parsing degli argomenti CLI.
"process.env.bagel" = "'lox'"

loader

Configura come Bun mappa le estensioni dei file ai loader. Questo è utile per caricare file che non sono supportati nativamente da Bun.

bunfig.toml

[loader]
# quando un file .bagel viene importato, trattalo come un file tsx
".bagel" = "tsx"

Bun supporta i seguenti loader:

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

telemetry

Il campo telemetry è usato per abilitare/disabilitare l'analytics. Di default, la telemetria è abilitata. Questo è equivalente alla variabile d'ambiente DO_NOT_TRACK.

Attualmente non raccogliamo telemetria e questa impostazione è usata solo per abilitare/disabilitare i report di crash anonimi, ma in futuro pianifichiamo di raccogliere informazioni come quali API Bun vengono usate di più o quanto tempo impiega bun build.

bunfig.toml

telemetry = false

console

Configura il comportamento dell'output della console.

console.depth

Imposta la profondità predefinita per l'ispezione degli oggetti di console.log(). Default 2.

bunfig.toml

[console]
depth = 3

Questo controlla quanto profondamente gli oggetti annidati vengono visualizzati nell'output della console. Valori più alti mostrano più proprietà annidate ma possono produrre output verboso per oggetti complessi. Questa impostazione può essere sovrascritta dal flag CLI --console-depth.

Test runner

Il test runner è configurato sotto la sezione [test] del tuo bunfig.toml.

bunfig.toml

[test]
# la configurazione va qui

test.root

La directory root da cui eseguire i test. Default ..

bunfig.toml

[test]
root = "./__tests__"

test.preload

Come il campo preload di primo livello, ma si applica solo a bun test.

bunfig.toml

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

test.smol

Come il campo smol di primo livello, ma si applica solo a bun test.

bunfig.toml

[test]
smol = true

test.coverage

Abilita il report della copertura. Default false. Usa --coverage per sovrascrivere.

bunfig.toml

[test]
coverage = false

test.coverageThreshold

Per specificare una soglia di copertura. Di default, nessuna soglia è impostata. Se la tua suite di test non raggiunge o supera questa soglia, bun test uscirà con un codice di uscita non-zero per indicare il fallimento.

bunfig.toml

[test]

# per richiedere il 90% di copertura a livello di righe e funzioni
coverageThreshold = 0.9

Soglie diverse possono essere specificate per copertura a livello di righe, funzioni e istruzioni.

bunfig.toml

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

test.coverageSkipTestFiles

Se saltare i file di test quando si calcolano le statistiche di copertura. Default false.

bunfig.toml

[test]
coverageSkipTestFiles = false

test.coveragePathIgnorePatterns

Escludi file specifici o pattern di file dai report di copertura usando pattern glob. Può essere una singola stringa pattern o un array di pattern.

bunfig.toml

[test]
# Singolo pattern
coveragePathIgnorePatterns = "**/*.spec.ts"

# Pattern multipli
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

test.coverageReporter

Di default, i report di copertura verranno stampati sulla console. Per report di copertura persistenti in ambienti CI e per altri strumenti usa lcov.

bunfig.toml

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

test.coverageDir

Imposta il percorso dove i report di copertura verranno salvati. Nota che funziona solo per coverageReporter persistenti come lcov.

bunfig.toml

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

test.randomize

Esegui i test in ordine casuale. Default false.

bunfig.toml

[test]
randomize = true

Questo aiuta a catturare bug relativi a interdipendenze dei test eseguendo i test in un ordine diverso ogni volta. Quando combinato con seed, l'ordine casuale diventa riproducibile.

Il flag CLI --randomize sovrascriverà questa impostazione quando specificato.

test.seed

Imposta il seed casuale per la randomizzazione dei test. Questa opzione richiede che randomize sia true.

bunfig.toml

[test]
randomize = true
seed = 2444615283

Usare un seed rende l'ordine randomizzato dei test riproducibile tra le esecuzioni, il che è utile per il debug di test instabili. Quando incontri un fallimento del test con la randomizzazione abilitata, puoi usare lo stesso seed per riprodurre l'esatto ordine dei test.

Il flag CLI --seed sovrascriverà questa impostazione quando specificato.

test.rerunEach

Riesegui ogni file di test un numero specificato di volte. Default 0 (esegui una volta).

bunfig.toml

[test]
rerunEach = 3

Questo è utile per catturare test instabili o comportamenti non deterministici. Ogni file di test verrà eseguito il numero di volte specificato.

Il flag CLI --rerun-each sovrascriverà questa impostazione quando specificato.

test.concurrentTestGlob

Specifica un pattern glob per eseguire automaticamente i file di test corrispondenti con l'esecuzione concorrente dei test abilitata. I file di test che corrispondono a questo pattern si comporteranno come se il flag --concurrent fosse stato passato, eseguendo tutti i test all'interno di quei file concorrentemente.

bunfig.toml

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

Questo è utile per:

• Migrare gradualmente le suite di test all'esecuzione concorrente
• Eseguire i test di integrazione concorrentemente mantenendo i test unitari sequenziali
• Separare i test concorrenti veloci dai test che richiedono esecuzione sequenziale

Il flag CLI --concurrent sovrascriverà questa impostazione quando specificato.

test.onlyFailures

Quando abilitato, solo i test falliti vengono visualizzati nell'output. Questo aiuta a ridurre il rumore in grandi suite di test nascondendo i test passati. Default false.

bunfig.toml

[test]
onlyFailures = true

Questo è equivalente all'uso del flag --only-failures quando si esegue bun test.

test.reporter

Configura le impostazioni del reporter dei test.

test.reporter.dots

Abilita il reporter dots, che visualizza un output compatto mostrando un punto per ogni test. Default false.

bunfig.toml

[test.reporter]
dots = true

test.reporter.junit

Abilita il report XML JUnit e specifica il percorso del file di output.

bunfig.toml

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

Questo genera un report JUnit XML che può essere consumato da sistemi CI e altri strumenti.

Package manager

La gestione dei pacchetti è un problema complesso; per supportare una serie di casi d'uso, il comportamento di bun install può essere configurato sotto la sezione [install].

bunfig.toml

[install]
# configurazione qui

install.optional

Se installare le dipendenze opzionali. Default true.

bunfig.toml

[install]
optional = true

install.dev

Se installare le dipendenze di sviluppo. Default true.

bunfig.toml

[install]
dev = true

install.peer

Se installare le dipendenze peer. Default true.

bunfig.toml

[install]
peer = true

install.production

Se bun install verrà eseguito in "modalità produzione". Default false.

In modalità produzione, "devDependencies" non vengono installate. Puoi usare --production nella CLI per sovrascrivere questa impostazione.

bunfig.toml

[install]
production = false

install.exact

Se impostare una versione esatta in package.json. Default false.

Di default Bun usa intervalli caret; se la versione latest di un pacchetto è 2.4.1, l'intervallo di versioni nel tuo package.json sarà ^2.4.1. Questo indica che qualsiasi versione da 2.4.1 fino a (ma non incluso) 3.0.0 è accettabile.

bunfig.toml

[install]
exact = false

install.saveTextLockfile

Se false, genera un bun.lockb binario invece di un file bun.lock basato su testo quando si esegue bun install e nessun lockfile è presente.

Default true (da Bun v1.2).

bunfig.toml

[install]
saveTextLockfile = false

install.auto

Per configurare il comportamento di auto-installazione dei pacchetti di Bun. Default "auto" — quando nessuna cartella node_modules viene trovata, Bun installerà automaticamente le dipendenze al volo durante l'esecuzione.

bunfig.toml

[install]
auto = "auto"

I valori validi sono:

Valore	Descrizione
"auto"	Risolvi i moduli da node_modules locale se esiste. Altrimenti, auto-installa le dipendenze al volo.
"force"	Auto-installa sempre le dipendenze, anche se node_modules esiste.
"disable"	Non auto-installare mai le dipendenze.
"fallback"	Controlla prima node_modules locale, poi auto-installa eventuali pacchetti che non vengono trovati. Puoi abilitare questo dalla CLI con bun -i.

install.frozenLockfile

Quando true, bun install non aggiornerà bun.lock. Default false. Se package.json e il bun.lock esistente non sono d'accordo, questo genererà un errore.

bunfig.toml

[install]
frozenLockfile = false

install.dryRun

Se bun install installerà effettivamente le dipendenze. Default false. Quando true, è equivalente a impostare --dry-run su tutti i comandi bun install.

bunfig.toml

[install]
dryRun = false

install.globalDir

Per configurare la directory dove Bun mette i pacchetti installati globalmente.

Variabile d'ambiente: BUN_INSTALL_GLOBAL_DIR

bunfig.toml

[install]
# dove `bun install --global` installa i pacchetti
globalDir = "~/.bun/install/global"

install.globalBinDir

Per configurare la directory dove Bun installa i binari e CLI installati globalmente.

Variabile d'ambiente: BUN_INSTALL_BIN

bunfig.toml

[install]
# dove i bin dei pacchetti installati globalmente vengono linkati
globalBinDir = "~/.bun/bin"

install.registry

Il registry predefinito è https://registry.npmjs.org/. Questo può essere configurato globalmente in bunfig.toml:

bunfig.toml

[install]
# imposta il registry predefinito come stringa
registry = "https://registry.npmjs.org"
# imposta un token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# imposta un nome utente/password
registry = "https://username:password@registry.npmjs.org"

install.linkWorkspacePackages

Per configurare come i pacchetti workspace vengono linkati, usa l'opzione install.linkWorkspacePackages.

Se linkare i pacchetti workspace dalla root del monorepo alle rispettive directory node_modules. Default true.

bunfig.toml

[install]
linkWorkspacePackages = true

install.scopes

Per configurare un registry per uno scope particolare (es. @myorg/<package>) usa install.scopes. Puoi fare riferimento a variabili d'ambiente con la notazione $variable.

bunfig.toml

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

# registry con nome utente/password
# puoi fare riferimento a variabili d'ambiente
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

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

install.ca e install.cafile

Per configurare un certificato CA, usa install.ca o install.cafile per specificare un percorso a un file di certificato CA.

bunfig.toml

[install]
# Il certificato CA come stringa
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# Un percorso a un file di certificato CA. Il file può contenere più certificati.
cafile = "path/to/cafile"

install.cache

Per configurare il comportamento della cache:

bunfig.toml

[install.cache]

# la directory da usare per la cache
dir = "~/.bun/install/cache"

# quando true, non caricare dalla cache globale.
# Bun può ancora scrivere su node_modules/.cache
disable = false

# quando true, risolvi sempre le versioni latest dal registry
disableManifest = false

install.lockfile

Per configurare il comportamento del lockfile, usa la sezione install.lockfile.

Se generare un lockfile su bun install. Default true.

bunfig.toml

[install.lockfile]
save = true

Se generare un lockfile non-Bun insieme a bun.lock. (Un bun.lock verrà sempre creato.) Attualmente "yarn" è l'unico valore supportato.

bunfig.toml

[install.lockfile]
print = "yarn"

install.linker

Configura la strategia del linker per installare le dipendenze. Default "isolated" per nuovi workspace, "hoisted" per nuovi progetti a pacchetto singolo e progetti esistenti (creati pre-v1.3.2).

Per la documentazione completa fai riferimento a Package manager > Installazioni isolate.

bunfig.toml

[install]
linker = "hoisted"

I valori validi sono:

Valore	Descrizione
"hoisted"	Linka le dipendenze in una directory node_modules condivisa.
"isolated"	Linka le dipendenze all'interno di ogni installazione del pacchetto.

bunfig.toml

[debug]
# Quando navighi su un link blob: o src:, apri il file nel tuo editor
# Se non funziona, prova $EDITOR o $VISUAL
# Se ancora fallisce, proverà Visual Studio Code, poi Sublime Text, poi alcuni altri
# Questo è usato da Bun.openInEditor()
editor = "code"

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

install.security.scanner

Configura uno scanner di sicurezza per scansionare i pacchetti per vulnerabilità prima dell'installazione.

Prima, installa uno scanner di sicurezza da npm:

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

Poi configuralo nel tuo bunfig.toml:

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

Quando uno scanner di sicurezza è configurato:

• L'auto-installazione viene automaticamente disabilitata per sicurezza
• I pacchetti vengono scansionati prima dell'installazione
• L'installazione viene annullata se vengono trovati problemi fatali
• Gli avvisi di sicurezza vengono visualizzati durante l'installazione

Scopri di più su uso e scrittura di scanner di sicurezza.

install.minimumReleaseAge

Configura un'età minima (in secondi) per le versioni dei pacchetti npm. Le versioni dei pacchetti pubblicate più recentemente di questa soglia verranno filtrate durante l'installazione. Default è null (disabilitato).

bunfig.toml

[install]
# Installa solo versioni di pacchetti pubblicate almeno 3 giorni fa
minimumReleaseAge = 259200
# Questi pacchetti bypasseranno il requisito di età minima di 3 giorni
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

Per maggiori dettagli vedi Età minima di release nella documentazione di install.

bun run

Il comando bun run può essere configurato sotto la sezione [run]. Questi si applicano al comando bun run e al comando bun quando si esegue un file o eseguibile o script.

Attualmente, bunfig.toml viene caricato automaticamente solo per bun run in un progetto locale (non controlla per un .bunfig.toml globale).

run.shell - usa la shell di sistema o la shell di Bun

La shell da usare quando si eseguono script package.json tramite bun run o bun. Su Windows, il default è "bun" e su altre piattaforme il default è "system".

Per usare sempre la shell di sistema invece della shell di Bun (comportamento predefinito a meno che Windows):

bunfig.toml

[run]
# default fuori da Windows
shell = "system"

Per usare sempre la shell di Bun invece della shell di sistema:

bunfig.toml

[run]
# default su Windows
shell = "bun"

run.bun - alias automatico node a bun

Quando true, questo prepone $PATH con un symlink node che punta al binario bun per tutti gli script o eseguibili invocati da bun run o bun.

Questo significa che se hai uno script che esegue node, eseguirà effettivamente bun invece, senza bisogno di cambiare il tuo script. Questo funziona ricorsivamente, quindi se il tuo script esegue un altro script che esegue node, eseguirà anche bun invece. Questo si applica anche agli shebang, quindi se hai uno script con uno shebang che punta a node, eseguirà effettivamente bun invece.

Di default, questo è abilitato se node non è già nel tuo $PATH.

bunfig.toml

[run]
# equivalente a `bun --bun` per tutti i comandi `bun run`
bun = true

Puoi testare questo eseguendo:

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

Questa opzione è equivalente a preporre tutti i comandi bun run con --bun:

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

Se impostato su false, questo disabiliterà il symlink node.

run.silent - sopprimi il report del comando in esecuzione

Quando true, sopprime l'output del comando in esecuzione da bun run o bun.

bunfig.toml

[run]
silent = true

Senza questa opzione, il comando in esecuzione verrà stampato sulla console:

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

Running "dev"...

Con questa opzione, il comando in esecuzione non verrà stampato sulla console:

bun run dev

Running "dev"...

Questo è equivalente a passare --silent a tutti i comandi bun run:

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