Le comportement de Bun peut être configuré en utilisant son fichier de configuration, bunfig.toml.

En général, Bun s'appuie sur des fichiers de configuration préexistants comme package.json et tsconfig.json pour configurer son comportement. bunfig.toml est uniquement nécessaire pour configurer des éléments spécifiques à Bun. Ce fichier est optionnel et Bun fonctionnera sans lui dès l'installation.

Global vs. local

En général, il est recommandé d'ajouter un fichier bunfig.toml à la racine de votre projet, à côté de votre package.json.

Pour configurer Bun globalement, vous pouvez également créer un fichier .bunfig.toml à l'un des chemins suivants :

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

Si un bunfig global et local sont détectés, les résultats sont fusionnés superficiellement, le local l'emportant sur le global. Les indicateurs CLI remplaceront les paramètres bunfig le cas échéant.

Runtime

Le comportement d'exécution de Bun est configuré en utilisant des champs de premier niveau dans le fichier bunfig.toml.

preload

Un tableau de scripts/plugins à exécuter avant d'exécuter un fichier ou un script.

bunfig.toml

# scripts à exécuter avant `bun run` d'un fichier ou script
# enregistrez les plugins en les ajoutant à cette liste
preload = ["./preload.ts"]

jsx

Configurez comment Bun gère JSX. Vous pouvez également définir ces champs dans les compilerOptions de votre tsconfig.json, mais ils sont également pris en charge ici pour les projets non-TypeScript.

bunfig.toml

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

Consultez la documentation tsconfig pour plus d'informations sur ces champs.

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol

Activez le mode smol. Cela réduit l'utilisation de la mémoire au détriment des performances.

bunfig.toml

# Réduire l'utilisation de la mémoire au détriment des performances
smol = true

logLevel

Définissez le niveau de journalisation. Cela peut être l'une des valeurs "debug", "warn" ou "error".

bunfig.toml

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

define

Le champ define vous permet de remplacer certains identifiants globaux par des expressions constantes. Bun remplacera toute utilisation de l'identifiant par l'expression. L'expression doit être une chaîne JSON.

bunfig.toml

[define]
# Remplace toute utilisation de "process.env.bagel" par la chaîne `lox`.
# Les valeurs sont analysées en tant que JSON, sauf que les chaînes entre guillemets simples sont prises en charge et `'undefined'` devient `undefined` en JS.
# Cela changera probablement dans une version future pour être du TOML régulier à la place. C'est un reliquat de l'analyse des arguments CLI.
"process.env.bagel" = "'lox'"

loader

Configurez comment Bun mappe les extensions de fichier aux loaders. Cela est utile pour charger des fichiers qui ne sont pas nativement pris en charge par Bun.

bunfig.toml

[loader]
# lorsqu'un fichier .bagel est importé, le traiter comme un fichier tsx
".bagel" = "tsx"

Bun prend en charge les loaders suivants :

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

telemetry

Le champ telemetry est utilisé pour activer/désactiver l'analytique. Par défaut, la télémétrie est activée. Cela équivaut à la variable d'environnement DO_NOT_TRACK.

Actuellement, nous ne collectons pas de télémétrie et ce paramètre est uniquement utilisé pour activer/désactiver les rapports de plantage anonymes, mais à l'avenir, nous prévoyons de collecter des informations telles que les APIs Bun les plus utilisées ou la durée de bun build.

bunfig.toml

telemetry = false

console

Configurez le comportement de sortie de la console.

console.depth

Définissez la profondeur par défaut pour l'inspection d'objet console.log(). Par défaut 2.

bunfig.toml

[console]
depth = 3

Cela contrôle la profondeur à laquelle les objets imbriqués sont affichés dans la sortie de la console. Des valeurs plus élevées affichent plus de propriétés imbriquées mais peuvent produire une sortie verbeuse pour des objets complexes. Ce paramètre peut être remplacé par l'indicateur CLI --console-depth.

Test runner

Le test runner est configuré dans la section [test] de votre bunfig.toml.

bunfig.toml

[test]
# la configuration va ici

test.root

Le répertoire racine à partir duquel exécuter les tests. Par défaut ..

bunfig.toml

[test]
root = "./__tests__"

test.preload

Identique au champ preload de premier niveau, mais s'applique uniquement à bun test.

bunfig.toml

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

test.smol

Identique au champ smol de premier niveau, mais s'applique uniquement à bun test.

bunfig.toml

[test]
smol = true

test.coverage

Active les rapports de couverture. Par défaut false. Utilisez --coverage pour remplacer.

bunfig.toml

[test]
coverage = false

test.coverageThreshold

Pour spécifier un seuil de couverture. Par défaut, aucun seuil n'est défini. Si votre suite de tests n'atteint pas ou ne dépasse pas ce seuil, bun test se terminera avec un code de sortie non nul pour indiquer l'échec.

bunfig.toml

[test]

# pour exiger 90% de couverture au niveau des lignes et des fonctions
coverageThreshold = 0.9

Différents seuils peuvent être spécifiés pour la couverture ligne par ligne, fonction par fonction et instruction par instruction.

bunfig.toml

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

test.coverageSkipTestFiles

Indique s'il faut ignorer les fichiers de test lors du calcul des statistiques de couverture. Par défaut false.

bunfig.toml

[test]
coverageSkipTestFiles = false

test.coveragePathIgnorePatterns

Excluez des fichiers ou des modèles de fichiers spécifiques des rapports de couverture en utilisant des modèles glob. Peut être un modèle de chaîne unique ou un tableau de modèles.

bunfig.toml

[test]
# Modèle unique
coveragePathIgnorePatterns = "**/*.spec.ts"

# Modèles multiples
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

test.coverageReporter

Par défaut, les rapports de couverture seront imprimés dans la console. Pour des rapports de couverture de code persistants dans les environnements CI et pour d'autres outils, utilisez lcov.

bunfig.toml

[test]
coverageReporter  = ["text", "lcov"]  # par défaut ["text"]

test.coverageDir

Définissez le chemin où les rapports de couverture seront enregistrés. Veuillez noter que cela ne fonctionne que pour les coverageReporter persistants comme lcov.

bunfig.toml

[test]
coverageDir = "path/to/somewhere"  # par défaut "coverage"

test.randomize

Exécutez les tests dans un ordre aléatoire. Par défaut false.

bunfig.toml

[test]
randomize = true

Cela aide à détecter les bugs liés aux interdépendances des tests en exécutant les tests dans un ordre différent à chaque fois. Lorsqu'il est combiné avec seed, l'ordre aléatoire devient reproductible.

L'indicateur CLI --randomize remplacera ce paramètre lorsqu'il est spécifié.

test.seed

Définissez la graine aléatoire pour la randomisation des tests. Cette option nécessite que randomize soit true.

bunfig.toml

[test]
randomize = true
seed = 2444615283

L'utilisation d'une graine rend l'ordre de test randomisé reproductible entre les exécutions, ce qui est utile pour déboguer les tests instables. Lorsque vous rencontrez un échec de test avec la randomisation activée, vous pouvez utiliser la même graine pour reproduire l'ordre de test exact.

L'indicateur CLI --seed remplacera ce paramètre lorsqu'il est spécifié.

test.rerunEach

Réexécutez chaque fichier de test un nombre spécifié de fois. Par défaut 0 (exécuter une fois).

bunfig.toml

[test]
rerunEach = 3

Cela est utile pour détecter les tests instables ou les comportements non déterministes. Chaque fichier de test sera exécuté le nombre de fois spécifié.

L'indicateur CLI --rerun-each remplacera ce paramètre lorsqu'il est spécifié.

test.concurrentTestGlob

Spécifiez un modèle glob pour exécuter automatiquement les fichiers de test correspondants avec l'exécution de test concurrente activée. Les fichiers de test correspondant à ce modèle se comporteront comme si l'indicateur --concurrent avait été passé, exécutant tous les tests dans ces fichiers de manière concurrente.

bunfig.toml

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

Cela est utile pour :

• Migrer progressivement les suites de tests vers une exécution concurrente
• Exécuter des tests d'intégration de manière concurrente tout en gardant les tests unitaires séquentiels
• Séparer les tests concurrents rapides des tests qui nécessitent une exécution séquentielle

L'indicateur CLI --concurrent remplacera ce paramètre lorsqu'il est spécifié.

test.onlyFailures

Lorsqu'il est activé, seuls les tests échoués sont affichés dans la sortie. Cela aide à réduire le bruit dans les grandes suites de tests en masquant les tests réussis. Par défaut false.

bunfig.toml

[test]
onlyFailures = true

Cela équivaut à utiliser l'indicateur --only-failures lors de l'exécution de bun test.

test.reporter

Configurez les paramètres du rapporteur de tests.

test.reporter.dots

Activez le rapporteur dots, qui affiche une sortie compacte montrant un point pour chaque test. Par défaut false.

bunfig.toml

[test.reporter]
dots = true

test.reporter.junit

Activez les rapports JUnit XML et spécifiez le chemin du fichier de sortie.

bunfig.toml

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

Cela génère un rapport JUnit XML qui peut être consommé par les systèmes CI et d'autres outils.

Package manager

La gestion des packages est un problème complexe ; pour prendre en charge un éventail de cas d'utilisation, le comportement de bun install peut être configuré dans la section [install].

bunfig.toml

[install]
# configuration ici

install.optional

Indique s'il faut installer les dépendances optionnelles. Par défaut true.

bunfig.toml

[install]
optional = true

install.dev

Indique s'il faut installer les dépendances de développement. Par défaut true.

bunfig.toml

[install]
dev = true

install.peer

Indique s'il faut installer les dépendances peer. Par défaut true.

bunfig.toml

[install]
peer = true

install.production

Indique si bun install s'exécutera en "mode production". Par défaut false.

En mode production, les "devDependencies" ne sont pas installées. Vous pouvez utiliser --production dans le CLI pour remplacer ce paramètre.

bunfig.toml

[install]
production = false

install.exact

Indique s'il faut définir une version exacte dans package.json. Par défaut false.

Par défaut, Bun utilise des plages caret ; si la version latest d'un package est 2.4.1, la plage de versions dans votre package.json sera ^2.4.1. Cela indique que toute version de 2.4.1 jusqu'à (mais non comprise) 3.0.0 est acceptable.

bunfig.toml

[install]
exact = false

install.saveTextLockfile

Si false, génère un bun.lockb binaire au lieu d'un fichier bun.lock basé sur du texte lors de l'exécution de bun install et qu'aucun lockfile n'est présent.

Par défaut true (depuis Bun v1.2).

bunfig.toml

[install]
saveTextLockfile = false

install.auto

Pour configurer le comportement d'installation automatique des packages de Bun. Par défaut "auto" — lorsqu'aucun dossier node_modules n'est trouvé, Bun installera automatiquement les dépendances à la volée pendant l'exécution.

bunfig.toml

[install]
auto = "auto"

Les valeurs valides sont :

Valeur	Description
"auto"	Résout les modules depuis le node_modules local s'il existe. Sinon, installe automatiquement les dépendances à la volée.
"force"	Installe toujours automatiquement les dépendances, même si node_modules existe.
"disable"	N'installe jamais automatiquement les dépendances.
"fallback"	Vérifie d'abord le node_modules local, puis installe automatiquement tous les packages introuvables. Vous pouvez activer cela depuis le CLI avec bun -i.

install.frozenLockfile

Lorsqu'il est vrai, bun install ne mettra pas à jour bun.lock. Par défaut false. Si package.json et le bun.lock existant ne sont pas d'accord, cela générera une erreur.

bunfig.toml

[install]
frozenLockfile = false

install.dryRun

Indique si bun install installera réellement les dépendances. Par défaut false. Lorsqu'il est vrai, cela équivaut à définir --dry-run sur toutes les commandes bun install.

bunfig.toml

[install]
dryRun = false

install.globalDir

Pour configurer le répertoire où Bun place les packages installés globalement.

Variable d'environnement : BUN_INSTALL_GLOBAL_DIR

bunfig.toml

[install]
# où `bun install --global` installe les packages
globalDir = "~/.bun/install/global"

install.globalBinDir

Pour configurer le répertoire où Bun installe les binaires et CLIs installés globalement.

Variable d'environnement : BUN_INSTALL_BIN

bunfig.toml

[install]
# où les bins de packages installés globalement sont liés
globalBinDir = "~/.bun/bin"

install.registry

Le registre par défaut est https://registry.npmjs.org/. Cela peut être configuré globalement dans bunfig.toml :

bunfig.toml

[install]
# définir le registre par défaut comme une chaîne
registry = "https://registry.npmjs.org"
# définir un token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# définir un nom d'utilisateur/mot de passe
registry = "https://username:password@registry.npmjs.org"

install.linkWorkspacePackages

Pour configurer comment les packages d'espace de travail sont liés, utilisez l'option install.linkWorkspacePackages.

Indique s'il faut lier les packages d'espace de travail depuis la racine du monorepo vers leurs répertoires node_modules respectifs. Par défaut true.

bunfig.toml

[install]
linkWorkspacePackages = true

install.scopes

Pour configurer un registre pour un scope particulier (par exemple @myorg/<package>) utilisez install.scopes. Vous pouvez référencer des variables d'environnement avec la notation $variable.

bunfig.toml

[install.scopes]
# registre comme chaîne
myorg = "https://username:password@registry.myorg.com/"

# registre avec nom d'utilisateur/mot de passe
# vous pouvez référencer des variables d'environnement
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

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

install.ca et install.cafile

Pour configurer un certificat CA, utilisez install.ca ou install.cafile pour spécifier un chemin vers un fichier de certificat CA.

bunfig.toml

[install]
# Le certificat CA comme chaîne
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# Un chemin vers un fichier de certificat CA. Le fichier peut contenir plusieurs certificats.
cafile = "path/to/cafile"

install.cache

Pour configurer le comportement du cache :

bunfig.toml

[install.cache]

# le répertoire à utiliser pour le cache
dir = "~/.bun/install/cache"

# lorsqu'il est vrai, ne pas charger depuis le cache global.
# Bun peut toujours écrire dans node_modules/.cache
disable = false

# lorsqu'il est vrai, toujours résoudre les dernières versions depuis le registre
disableManifest = false

install.lockfile

Pour configurer le comportement du lockfile, utilisez la section install.lockfile.

Indique s'il faut générer un lockfile lors de bun install. Par défaut true.

bunfig.toml

[install.lockfile]
save = true

Indique s'il faut générer un lockfile non-Bun aux côtés de bun.lock. (Un bun.lock sera toujours créé.) Actuellement, "yarn" est la seule valeur prise en charge.

bunfig.toml

[install.lockfile]
print = "yarn"

install.linker

Configurez la stratégie de linker pour l'installation des dépendances. Par défaut à "isolated" pour les nouveaux espaces de travail, "hoisted" pour les nouveaux projets à package unique et les projets existants (créés avant la v1.3.2).

Pour une documentation complète, consultez Package manager > Installations isolées.

bunfig.toml

[install]
linker = "hoisted"

Les valeurs valides sont :

Valeur	Description
"hoisted"	Lie les dépendances dans un répertoire node_modules partagé.
"isolated"	Lie les dépendances à l'intérieur de chaque installation de package.

bunfig.toml

[debug]
# Lors de la navigation vers un lien blob: ou src:, ouvrir le fichier dans votre éditeur
# Sinon, il essaie $EDITOR ou $VISUAL
# Si cela échoue toujours, il essaiera Visual Studio Code, puis Sublime Text, puis quelques autres
# Ceci est utilisé par Bun.openInEditor()
editor = "code"

# Liste des éditeurs :
# - "subl", "sublime"
# - "vscode", "code"
# - "textmate", "mate"
# - "idea"
# - "webstorm"
# - "nvim", "neovim"
# - "vim","vi"
# - "emacs"

install.security.scanner

Configurez un analyseur de sécurité pour analyser les packages à la recherche de vulnérabilités avant l'installation.

Tout d'abord, installez un analyseur de sécurité depuis npm :

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

Ensuite, configurez-le dans votre bunfig.toml :

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

Lorsqu'un analyseur de sécurité est configuré :

• L'installation automatique est automatiquement désactivée pour la sécurité
• Les packages sont analysés avant l'installation
• L'installation est annulée si des problèmes critiques sont trouvés
• Les avertissements de sécurité sont affichés pendant l'installation

Apprenez-en plus sur l'utilisation et l'écriture d'analyseurs de sécurité.

install.minimumReleaseAge

Configurez un âge minimum (en secondes) pour les versions de packages npm. Les versions de packages publiées plus récemment que ce seuil seront filtrées pendant l'installation. Par défaut null (désactivé).

bunfig.toml

[install]
# Installer uniquement les versions de packages publiées il y a au moins 3 jours
minimumReleaseAge = 259200
# Ces packages contourneront l'exigence d'âge minimum de 3 jours
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

Pour plus de détails, consultez Âge de publication minimum dans la documentation d'installation.

bun run

La commande bun run peut être configurée dans la section [run]. Cela s'applique à la commande bun run et à la commande bun lors de l'exécution d'un fichier, d'un exécutable ou d'un script.

Actuellement, bunfig.toml est uniquement chargé automatiquement pour bun run dans un projet local (il ne vérifie pas un .bunfig.toml global).

run.shell - utiliser le shell système ou le shell de Bun

Le shell à utiliser lors de l'exécution de scripts package.json via bun run ou bun. Sur Windows, cela prend par défaut la valeur "bun" et sur d'autres plateformes, cela prend par défaut la valeur "system".

Pour toujours utiliser le shell système au lieu du shell de Bun (comportement par défaut sauf sur Windows) :

bunfig.toml

[run]
# par défaut en dehors de Windows
shell = "system"

Pour toujours utiliser le shell de Bun au lieu du shell système :

bunfig.toml

[run]
# par défaut sur Windows
shell = "bun"

run.bun - alias automatique de node vers bun

Lorsqu'il est vrai, cela préfixe $PATH avec un lien symbolique node qui pointe vers le binaire bun pour tous les scripts ou exécutables invoqués par bun run ou bun.

Cela signifie que si vous avez un script qui exécute node, il exécutera en fait bun à la place, sans avoir besoin de modifier votre script. Cela fonctionne de manière récursive, donc si votre script exécute un autre script qui exécute node, il exécutera également bun à la place. Cela s'applique également aux shebangs, donc si vous avez un script avec un shebang qui pointe vers node, il exécutera en fait bun à la place.

Par défaut, cela est activé si node n'est pas déjà dans votre $PATH.

bunfig.toml

[run]
# équivalent à `bun --bun` pour toutes les commandes `bun run`
bun = true

Vous pouvez tester cela en exécutant :

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

Cette option équivaut à préfixer toutes les commandes bun run avec --bun :

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

Si défini sur false, cela désactivera le lien symbolique node.

run.silent - supprimer le rapport de la commande en cours d'exécution

Lorsqu'il est vrai, supprime la sortie de la commande en cours d'exécution par bun run ou bun.

bunfig.toml

[run]
silent = true

Sans cette option, la commande en cours d'exécution sera imprimée dans la console :

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

Running "dev"...

Avec cette option, la commande en cours d'exécution ne sera pas imprimée dans la console :

bun run dev

Running "dev"...

Cela équivaut à passer --silent à toutes les commandes bun run :

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