Bun's Verhalten kann mit der Konfigurationsdatei bunfig.toml konfiguriert werden.

Im Allgemeinen verlässt sich Bun auf bereits vorhandene Konfigurationsdateien wie package.json und tsconfig.json, um sein Verhalten zu konfigurieren. bunfig.toml ist nur für die Konfiguration von Bun-spezifischen Dingen erforderlich. Diese Datei ist optional, und Bun wird auch ohne sie funktionieren.

Global vs. lokal

Im Allgemeinen wird empfohlen, eine bunfig.toml-Datei im Projektstammverzeichnis neben Ihrer package.json hinzuzufügen.

Um Bun global zu konfigurieren, können Sie auch eine .bunfig.toml-Datei an einem der folgenden Pfade erstellen:

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

Wenn sowohl eine globale als auch eine lokale bunfig erkannt werden, werden die Ergebnisse flach zusammengeführt, wobei lokale Einstellungen globale überschreiben. CLI-Flags überschreiben bunfig-Einstellungen, wo anwendbar.

Runtime

Bun's Runtime-Verhalten wird mit Top-Level-Feldern in der bunfig.toml-Datei konfiguriert.

preload

Ein Array von Skripten/Plugins, die vor dem Ausführen einer Datei oder eines Skripts ausgeführt werden.

bunfig.toml

# Skripte, die vor `bun run` einer Datei oder eines Skripts ausgeführt werden
# Plugins registrieren, indem Sie sie zu dieser Liste hinzufügen
preload = ["./preload.ts"]

jsx

Konfigurieren, wie Bun JSX verarbeitet. Sie können diese Felder auch in den compilerOptions Ihrer tsconfig.json festlegen, aber sie werden hier auch für Nicht-TypeScript-Projekte unterstützt.

bunfig.toml

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

Weitere Informationen zu diesen Feldern finden Sie in der tsconfig-Dokumentation.

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol

Aktivieren Sie den smol-Modus. Dies reduziert den Speicherverbrauch auf Kosten der Leistung.

bunfig.toml

# Speicherverbrauch auf Kosten der Leistung reduzieren
smol = true

logLevel

Legen Sie die Protokollierungsstufe fest. Dies kann einer der Werte "debug", "warn" oder "error" sein.

bunfig.toml

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

define

Das define-Feld ermöglicht es Ihnen, bestimmte globale Bezeichner durch konstante Ausdrücke zu ersetzen. Bun ersetzt jede Verwendung des Bezeichners durch den Ausdruck. Der Ausdruck sollte ein JSON-String sein.

bunfig.toml

[define]
# Ersetzt jede Verwendung von "process.env.bagel" durch den String `lox`.
# Die Werte werden als JSON geparst, außer dass einfach zitierte Strings unterstützt werden und `'undefined'` zu `undefined` in JS wird.
# Dies wird sich wahrscheinlich in einer zukünftigen Version zu regulärem TOML ändern. Es ist ein Überbleibsel aus dem CLI-Argument-Parsing.
"process.env.bagel" = "'lox'"

loader

Konfigurieren, wie Bun Dateierweiterungen Loadern zuordnet. Dies ist nützlich für das Laden von Dateien, die von Bun nicht nativ unterstützt werden.

bunfig.toml

[loader]
# Wenn eine .bagel-Datei importiert wird, behandle sie wie eine tsx-Datei
".bagel" = "tsx"

Bun unterstützt die folgenden Loader:

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

telemetry

Das telemetry-Feld wird verwendet, um Analytics zu aktivieren/deaktivieren. Standardmäßig ist Telemetrie aktiviert. Dies entspricht der Umgebungsvariablen DO_NOT_TRACK.

Derzeit sammeln wir keine Telemetrie und diese Einstellung wird nur zum Aktivieren/Deaktivieren anonymer Absturzberichte verwendet, aber in Zukunft planen wir, Informationen wie die am häufigsten verwendeten Bun-APIs oder die Dauer von bun build zu sammeln.

bunfig.toml

telemetry = false

console

Konfigurieren Sie das Konsenausgabeverhalten.

console.depth

Legen Sie die Standardtiefe für die Objektinspektion von console.log() fest. Standard 2.

bunfig.toml

[console]
depth = 3

Dies steuert, wie tief verschachtelte Objekte in der Konsenausgabe angezeigt werden. Höhere Werte zeigen mehr verschachtelte Eigenschaften, können aber bei komplexen Objekten zu ausführlicher Ausgabe führen. Diese Einstellung kann durch das CLI-Flag --console-depth überschrieben werden.

Test-Runner

Der Test-Runner wird im [test]-Abschnitt Ihrer bunfig.toml konfiguriert.

bunfig.toml

[test]
# Konfiguration hier

test.root

Das Stammverzeichnis, von dem aus Tests ausgeführt werden. Standard ..

bunfig.toml

[test]
root = "./__tests__"

test.preload

Gleich wie das Top-Level-preload-Feld, gilt aber nur für bun test.

bunfig.toml

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

test.smol

Gleich wie das Top-Level-smol-Feld, gilt aber nur für bun test.

bunfig.toml

[test]
smol = true

test.coverage

Aktiviert die Coverage-Berichterstattung. Standard false. Verwenden Sie --coverage zum Überschreiben.

bunfig.toml

[test]
coverage = false

test.coverageThreshold

Um einen Coverage-Schwellenwert anzugeben. Standardmäßig ist kein Schwellenwert festgelegt. Wenn Ihre Testsuite diesen Schwellenwert nicht erreicht oder überschreitet, wird bun test mit einem Nicht-Null-Exit-Code beendet, um den Fehler anzuzeigen.

bunfig.toml

[test]

# Um 90% Zeilen- und Funktions-Coverage zu erfordern
coverageThreshold = 0.9

Verschiedene Schwellenwerte können für zeilenweise, funktionsweise und anweisungsweise Coverage angegeben werden.

bunfig.toml

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

test.coverageSkipTestFiles

Ob Testdateien bei der Berechnung der Coverage-Statistiken übersprungen werden sollen. Standard false.

bunfig.toml

[test]
coverageSkipTestFiles = false

test.coveragePathIgnorePatterns

Schließen Sie bestimmte Dateien oder Dateimuster von Coverage-Berichten unter Verwendung von Glob-Mustern aus. Kann ein einzelnes String-Muster oder ein Array von Mustern sein.

bunfig.toml

[test]
# Einzelnes Muster
coveragePathIgnorePatterns = "**/*.spec.ts"

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

test.coverageReporter

Standardmäßig werden Coverage-Berichte in der Konsole ausgegeben. Für persistente Code-Coverage-Berichte in CI-Umgebungen und für andere Tools verwenden Sie lcov.

bunfig.toml

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

test.coverageDir

Legen Sie den Pfad fest, unter dem Coverage-Berichte gespeichert werden. Beachten Sie, dass dies nur für persistente coverageReporter wie lcov funktioniert.

bunfig.toml

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

test.randomize

Führt Tests in zufälliger Reihenfolge aus. Standard false.

bunfig.toml

[test]
randomize = true

Dies hilft, Fehler im Zusammenhang mit Test-Interdependenzen zu erkennen, indem Tests bei jeder Ausführung in einer anderen Reihenfolge ausgeführt werden. In Kombination mit seed wird die zufällige Reihenfolge reproduzierbar.

Das CLI-Flag --randomize überschreibt diese Einstellung, wenn angegeben.

test.seed

Legen Sie den zufälligen Seed für die Test-Randomisierung fest. Diese Option erfordert, dass randomize auf true gesetzt ist.

bunfig.toml

[test]
randomize = true
seed = 2444615283

Die Verwendung eines Seeds macht die randomisierte Testreihenfolge über mehrere Durchläufe hinweg reproduzierbar, was für das Debugging von flaky Tests nützlich ist. Wenn Sie einen Testfehler bei aktivierter Randomisierung feststellen, können Sie denselben Seed verwenden, um die genaue Testreihenfolge zu reproduzieren.

Das CLI-Flag --seed überschreibt diese Einstellung, wenn angegeben.

test.rerunEach

Führt jede Testdatei eine angegebene Anzahl von Malen erneut aus. Standard 0 (einmal ausführen).

bunfig.toml

[test]
rerunEach = 3

Dies ist nützlich, um flaky Tests oder nicht-deterministisches Verhalten zu erkennen. Jede Testdatei wird die angegebene Anzahl von Malen ausgeführt.

Das CLI-Flag --rerun-each überschreibt diese Einstellung, wenn angegeben.

test.concurrentTestGlob

Geben Sie ein Glob-Muster an, um automatisch übereinstimmende Testdateien mit aktivierter gleichzeitiger Testausführung auszuführen. Testdateien, die diesem Muster entsprechen, verhalten sich so, als ob das --concurrent-Flag übergeben wurde, und führen alle Tests innerhalb dieser Dateien gleichzeitig aus.

bunfig.toml

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

Dies ist nützlich für:

• Allmähliche Migration von Testsuites zur gleichzeitigen Ausführung
• Gleichzeitiges Ausführen von Integrationstests bei sequentieller Ausführung von Unit-Tests
• Trennung von schnellen gleichzeitigen Tests von Tests, die eine sequentielle Ausführung erfordern

Das CLI-Flag --concurrent überschreibt diese Einstellung, wenn angegeben.

test.onlyFailures

Wenn aktiviert, werden nur fehlgeschlagene Tests in der Ausgabe angezeigt. Dies hilft, Rauschen in großen Testsuites zu reduzieren, indem bestandene Tests ausgeblendet werden. Standard false.

bunfig.toml

[test]
onlyFailures = true

Dies entspricht der Verwendung des --only-failures-Flags beim Ausführen von bun test.

test.reporter

Konfigurieren Sie die Test-Reporter-Einstellungen.

test.reporter.dots

Aktiviert den Dots-Reporter, der eine kompakte Ausgabe mit einem Punkt für jeden Test anzeigt. Standard false.

bunfig.toml

[test.reporter]
dots = true

test.reporter.junit

Aktiviert die JUnit XML-Berichterstattung und gibt den Ausgabedateipfad an.

bunfig.toml

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

Dies generiert einen JUnit XML-Bericht, der von CI-Systemen und anderen Tools konsumiert werden kann.

Package Manager

Package-Management ist ein komplexes Thema; um eine Reihe von Anwendungsfällen zu unterstützen, kann das Verhalten von bun install im [install]-Abschnitt konfiguriert werden.

bunfig.toml

[install]
# Konfiguration hier

install.optional

Ob optionale Abhängigkeiten installiert werden sollen. Standard true.

bunfig.toml

[install]
optional = true

install.dev

Ob Entwicklungsabhängigkeiten installiert werden sollen. Standard true.

bunfig.toml

[install]
dev = true

install.peer

Ob Peer-Abhängigkeiten installiert werden sollen. Standard true.

bunfig.toml

[install]
peer = true

install.production

Ob bun install im "Produktionsmodus" ausgeführt wird. Standard false.

Im Produktionsmodus werden "devDependencies" nicht installiert. Sie können --production in der CLI verwenden, um diese Einstellung zu überschreiben.

bunfig.toml

[install]
production = false

install.exact

Ob eine exakte Version in package.json festgelegt werden soll. Standard false.

Standardmäßig verwendet Bun Caret-Bereiche; wenn die latest-Version eines Pakets 2.4.1 ist, wird der Versionsbereich in Ihrer package.json ^2.4.1 sein. Dies zeigt an, dass jede Version von 2.4.1 bis (aber nicht einschließlich) 3.0.0 akzeptabel ist.

bunfig.toml

[install]
exact = false

install.saveTextLockfile

Wenn false, wird eine binäre bun.lockb anstelle einer textbasierten bun.lock-Datei generiert, wenn bun install ausgeführt wird und keine Lockfile vorhanden ist.

Standard true (seit Bun v1.2).

bunfig.toml

[install]
saveTextLockfile = false

install.auto

Um Bun's Paket-Auto-Install-Verhalten zu konfigurieren. Standard "auto" — wenn kein node_modules-Ordner gefunden wird, installiert Bun automatisch Abhängigkeiten während der Ausführung.

bunfig.toml

[install]
auto = "auto"

Gültige Werte sind:

Wert	Beschreibung
"auto"	Löst Module aus lokalem node_modules auf, falls vorhanden. Andernfalls werden Abhängigkeiten automatisch während der Ausführung installiert.
"force"	Installiert Abhängigkeiten immer automatisch, auch wenn node_modules vorhanden ist.
"disable"	Installiert niemals Abhängigkeiten automatisch.
"fallback"	Überprüft zuerst lokales node_modules, installiert dann automatisch alle Pakete, die nicht gefunden werden. Sie können dies über die CLI mit bun -i aktivieren.

install.frozenLockfile

Wenn true, wird bun install bun.lock nicht aktualisieren. Standard false. Wenn package.json und die vorhandene bun.lock nicht übereinstimmen, wird dies einen Fehler verursachen.

bunfig.toml

[install]
frozenLockfile = false

install.dryRun

Ob bun install tatsächlich Abhängigkeiten installiert. Standard false. Wenn true, entspricht dies dem Setzen von --dry-run bei allen bun install-Befehlen.

bunfig.toml

[install]
dryRun = false

install.globalDir

Um das Verzeichnis zu konfigurieren, in dem Bun global installierte Pakete ablegt.

Umgebungsvariable: BUN_INSTALL_GLOBAL_DIR

bunfig.toml

[install]
# Wo `bun install --global` Pakete installiert
globalDir = "~/.bun/install/global"

install.globalBinDir

Um das Verzeichnis zu konfigurieren, in dem Bun global installierte Binaries und CLIs installiert.

Umgebungsvariable: BUN_INSTALL_BIN

bunfig.toml

[install]
# Wo global installierte Paket-Binaries verknüpft werden
globalBinDir = "~/.bun/bin"

install.registry

Die Standard-Registry ist https://registry.npmjs.org/. Dies kann global in bunfig.toml konfiguriert werden:

bunfig.toml

[install]
# Standard-Registry als String festlegen
registry = "https://registry.npmjs.org"
# Ein Token festlegen
registry = { url = "https://registry.npmjs.org", token = "123456" }
# Einen Benutzernamen/Passwort festlegen
registry = "https://username:password@registry.npmjs.org"

install.linkWorkspacePackages

Um zu konfigurieren, wie Workspace-Pakete verknüpft werden, verwenden Sie die Option install.linkWorkspacePackages.

Ob Workspace-Pakete vom Monorepo-Stamm zu ihren jeweiligen node_modules-Verzeichnissen verknüpft werden sollen. Standard true.

bunfig.toml

[install]
linkWorkspacePackages = true

install.scopes

Um eine Registry für einen bestimmten Scope (z.B. @myorg/<package>) zu konfigurieren, verwenden Sie install.scopes. Sie können Umgebungsvariablen mit der $variable-Notation referenzieren.

bunfig.toml

[install.scopes]
# Registry als String
myorg = "https://username:password@registry.myorg.com/"

# Registry mit Benutzername/Passwort
# Sie können Umgebungsvariablen referenzieren
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

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

install.ca und install.cafile

Um ein CA-Zertifikat zu konfigurieren, verwenden Sie install.ca oder install.cafile, um einen Pfad zu einer CA-Zertifikatdatei anzugeben.

bunfig.toml

[install]
# Das CA-Zertifikat als String
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# Ein Pfad zu einer CA-Zertifikatdatei. Die Datei kann mehrere Zertifikate enthalten.
cafile = "path/to/cafile"

install.cache

Um das Cache-Verhalten zu konfigurieren:

bunfig.toml

[install.cache]

# Das Verzeichnis, das für den Cache verwendet werden soll
dir = "~/.bun/install/cache"

# Wenn true, nicht aus dem globalen Cache laden.
# Bun kann immer noch nach node_modules/.cache schreiben
disable = false

# Wenn true, immer die neuesten Versionen aus der Registry auflösen
disableManifest = false

install.lockfile

Um das Lockfile-Verhalten zu konfigurieren, verwenden Sie den install.lockfile-Abschnitt.

Ob bei bun install eine Lockfile generiert werden soll. Standard true.

bunfig.toml

[install.lockfile]
save = true

Ob eine Nicht-Bun-Lockfile neben bun.lock generiert werden soll. (Eine bun.lock wird immer erstellt.) Derzeit ist "yarn" der einzige unterstützte Wert.

bunfig.toml

[install.lockfile]
print = "yarn"

install.linker

Konfigurieren Sie die Linker-Strategie für die Installation von Abhängigkeiten. Standardmäßig "isolated" für neue Workspaces, "hoisted" für neue Single-Package-Projekte und bestehende Projekte (vor v1.3.2 erstellt).

Vollständige Dokumentation finden Sie unter Package Manager > Isolierte Installationen.

bunfig.toml

[install]
linker = "hoisted"

Gültige Werte sind:

Wert	Beschreibung
"hoisted"	Verknüpft Abhängigkeiten in einem gemeinsamen node_modules-Verzeichnis.
"isolated"	Verknüpft Abhängigkeiten innerhalb jeder Paketinstallation.

bunfig.toml

[debug]
# Beim Navigieren zu einem blob: oder src: Link die Datei in Ihrem Editor öffnen
# Wenn nicht, versucht es mit $EDITOR oder $VISUAL
# Wenn das immer noch fehlschlägt, versucht es mit Visual Studio Code, dann Sublime Text, dann ein paar anderen
# Dies wird von Bun.openInEditor() verwendet
editor = "code"

# Liste der Editoren:
# - "subl", "sublime"
# - "vscode", "code"
# - "textmate", "mate"
# - "idea"
# - "webstorm"
# - "nvim", "neovim"
# - "vim","vi"
# - "emacs"

install.security.scanner

Konfigurieren Sie einen Security-Scanner, um Pakete vor der Installation auf Schwachstellen zu überprüfen.

Installieren Sie zuerst einen Security-Scanner von npm:

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

Konfigurieren Sie ihn dann in Ihrer bunfig.toml:

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

Wenn ein Security-Scanner konfiguriert ist:

• Auto-Install wird aus Sicherheitsgründen automatisch deaktiviert
• Pakete werden vor der Installation gescannt
• Die Installation wird abgebrochen, wenn fatale Probleme gefunden werden
• Security-Warnungen werden während der Installation angezeigt

Erfahren Sie mehr über Verwenden und Schreiben von Security-Scannern.

install.minimumReleaseAge

Konfigurieren Sie ein Mindestalter (in Sekunden) für npm-Paketversionen. Paketversionen, die kürzer als dieser Schwellenwert veröffentlicht wurden, werden während der Installation herausgefiltert. Standard ist null (deaktiviert).

bunfig.toml

[install]
# Nur Paketversionen installieren, die vor mindestens 3 Tagen veröffentlicht wurden
minimumReleaseAge = 259200
# Diese Pakete umgehen die 3-Tage-Mindestalter-Anforderung
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

Weitere Details finden Sie unter Mindestveröffentlichungsalter in der Installationsdokumentation.

bun run

Der bun run-Befehl kann im [run]-Abschnitt konfiguriert werden. Diese gelten für den bun run-Befehl und den bun-Befehl beim Ausführen einer Datei oder eines ausführbaren Skripts.

Derzeit wird bunfig.toml nur automatisch für bun run in einem lokalen Projekt geladen (es sucht nicht nach einer globalen .bunfig.toml).

run.shell - Verwenden der System-Shell oder Bun's Shell

Die Shell, die beim Ausführen von package.json-Skripten über bun run oder bun verwendet wird. Unter Windows ist dies standardmäßig "bun" und auf anderen Plattformen standardmäßig "system".

Um immer die System-Shell anstelle von Bun's Shell zu verwenden (Standardverhalten außer unter Windows):

bunfig.toml

[run]
# Standard außerhalb von Windows
shell = "system"

Um immer Bun's Shell anstelle der System-Shell zu verwenden:

bunfig.toml

[run]
# Standard unter Windows
shell = "bun"

run.bun - Auto-Alias node zu bun

Wenn true, wird $PATH mit einem node-Symlink vorangestellt, der auf die bun-Binärdatei für alle Skripte oder ausführbaren Dateien zeigt, die von bun run oder bun aufgerufen werden.

Dies bedeutet, dass wenn Sie ein Skript haben, das node ausführt, es stattdessen tatsächlich bun ausführt, ohne dass Sie Ihr Skript ändern müssen. Dies funktioniert rekursiv, also wenn Ihr Skript ein anderes Skript ausführt, das node ausführt, wird es auch stattdessen bun ausführen. Dies gilt auch für Shebangs, also wenn Sie ein Skript mit einem Shebang haben, der auf node zeigt, wird es stattdessen tatsächlich bun ausführen.

Standardmäßig ist dies aktiviert, wenn node nicht bereits in Ihrem $PATH ist.

bunfig.toml

[run]
# Entspricht `bun --bun` für alle `bun run`-Befehle
bun = true

Sie können dies testen, indem Sie ausführen:

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

Diese Option entspricht dem Voranstellen aller bun run-Befehle mit --bun:

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

Wenn auf false gesetzt, wird dies den node-Symlink deaktivieren.

run.silent - Unterdrücken der Ausgabe des ausgeführten Befehls

Wenn true, wird die Ausgabe des von bun run oder bun ausgeführten Befehls unterdrückt.

bunfig.toml

[run]
silent = true

Ohne diese Option wird der ausgeführte Befehl in der Konsole ausgegeben:

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

Running "dev"...

Mit dieser Option wird der ausgeführte Befehl nicht in der Konsole ausgegeben:

bun run dev

Running "dev"...

Dies entspricht dem Übergeben von --silent an alle bun run-Befehle:

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