bunfig.toml

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.

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.

toml

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

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

`smol`

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

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

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.

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.

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.

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.

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.

toml

[test]
# la configuration va ici

`test.root`

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

toml

[test]
root = "./__tests__"

`test.preload`

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

toml

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

`test.smol`

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

toml

[test]
smol = true

`test.coverage`

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

toml

[test.reporter]
dots = true

`test.reporter.junit`

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

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

toml

[install]
# configuration ici

`install.optional`

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

toml

[install]
optional = true

`install.dev`

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

toml

[install]
dev = true

`install.peer`

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

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.

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.

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

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.

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.

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.

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

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

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 :

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.

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.

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.

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 :

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.

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.

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.

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.

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 :

bash

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

Ensuite, configurez-le dans votre bunfig.toml :

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é).

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

toml

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

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

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.

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.

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\"..."

txt

Running "dev"...

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

bun run dev

txt

Running "dev"...

Cela équivaut à passer --silent à toutes les commandes 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 et install.cafile ​

install.cache ​

install.lockfile ​

install.linker ​

install.security.scanner ​

install.minimumReleaseAge ​

bun run ​

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

run.bun - alias automatique de node vers bun ​

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

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

`install.cache`

`install.lockfile`

`install.linker`

`install.security.scanner`

`install.minimumReleaseAge`

`bun run`

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

`run.bun` - alias automatique de `node` vers `bun`

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