Der Bun Bundler implementiert ab Werk eine Reihe von Standard-Loadern.

Als Faustregel gilt: Der Bundler und die Runtime unterstützen beide ab Werk dieselben Dateitypen.

.js .cjs .mjs .mts .cts .ts .tsx .jsx .css .json .jsonc .toml .yaml .yml .txt .wasm .node .html .sh

Bun verwendet die Dateierweiterung, um zu bestimmen, welcher integrierte Loader zum Parsen der Datei verwendet werden soll. Jeder Loader hat einen Namen, wie js, tsx oder json. Diese Namen werden verwendet, wenn Plugins erstellt werden, die Bun mit benutzerdefinierten Loadern erweitern.

Sie können explizit angeben, welcher Loader verwendet werden soll, indem Sie das 'type'-Importattribut verwenden.

index.ts

import my_toml from "./my_file" with { type: "toml" };
// oder mit dynamischen Importen
const { default: my_toml } = await import("./my_file", { with: { type: "toml" } });

Integrierte Loader

js

JavaScript-Loader. Standard für .cjs und .mjs.

Parsen den Code und wenden eine Reihe von Standardtransformationen wie Dead-Code-Eliminierung und Tree-Shaking an. Beachten Sie, dass Bun derzeit nicht versucht, Syntax abwärts zu konvertieren.

---

jsx

JavaScript + JSX-Loader. Standard für .js und .jsx.

Gleich wie der js-Loader, aber JSX-Syntax wird unterstützt. Standardmäßig wird JSX in einfaches JavaScript abwärts konvertiert; die Details, wie dies geschieht, hängen von den jsx*-Compileroptionen in Ihrer tsconfig.json ab. Weitere Informationen finden Sie in der TypeScript-Dokumentation zu JSX.

---

ts

TypeScript-Loader. Standard für .ts, .mts und .cts.

Entfernt alle TypeScript-Syntax und verhält sich dann identisch wie der js-Loader. Bun führt keine Typprüfung durch.

---

tsx

TypeScript + JSX-Loader. Standard für .tsx.

Transpiliert sowohl TypeScript als auch JSX in Vanilla-JavaScript.

---

json

JSON-Loader. Standard für .json.

JSON-Dateien können direkt importiert werden.

import pkg from "./package.json";
pkg.name; // => "my-package"

Während des Bündelns wird das geparste JSON als JavaScript-Objekt in das Bundle inline eingefügt.

const pkg = {
  name: "my-package",
  // ... andere Felder
};

pkg.name;

Wenn eine .json-Datei als Einstiegspunkt an den Bundler übergeben wird, wird sie in ein .js-Modul konvertiert, das das geparste Objekt als export default exportiert.

{
  "name": "John Doe",
  "age": 35,
  "email": "johndoe@example.com"
}

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

---

jsonc

JSON mit Kommentaren-Loader. Standard für .jsonc.

JSONC-Dateien (JSON with Comments) können direkt importiert werden. Bun parst sie und entfernt Kommentare und nachgestellte Kommas.

import config from "./config.jsonc";
console.log(config);

Während des Bündelns wird das geparste JSONC als JavaScript-Objekt in das Bundle inline eingefügt, identisch wie der json-Loader.

var config = {
  option: "value",
};

NOTE

Bun verwendet automatisch den `jsonc`-Loader für `tsconfig.json`, `jsconfig.json`, `package.json` und `bun.lock`-Dateien.

---

toml

TOML-Loader. Standard für .toml.

TOML-Dateien können direkt importiert werden. Bun parst sie mit seinem schnellen nativen TOML-Parser.

import config from "./bunfig.toml";
config.logLevel; // => "debug"

// über Importattribut:
// import myCustomTOML from './my.config' with {type: "toml"};

Während des Bündelns wird das geparste TOML als JavaScript-Objekt in das Bundle inline eingefügt.

var config = {
  logLevel: "debug",
  // ...andere Felder
};
config.logLevel;

Wenn eine .toml-Datei als Einstiegspunkt übergeben wird, wird sie in ein .js-Modul konvertiert, das das geparste Objekt als export default exportiert.

name = "John Doe"
age = 35
email = "johndoe@example.com"

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

---

yaml

YAML-Loader. Standard für .yaml und .yml.

YAML-Dateien können direkt importiert werden. Bun parst sie mit seinem schnellen nativen YAML-Parser.

import config from "./config.yaml";
console.log(config);

// über Importattribut:
import data from "./data.txt" with { type: "yaml" };

Während des Bündelns wird das geparste YAML als JavaScript-Objekt in das Bundle inline eingefügt.

var config = {
  name: "my-app",
  version: "1.0.0",
  // ...andere Felder
};

Wenn eine .yaml- oder .yml-Datei als Einstiegspunkt übergeben wird, wird sie in ein .js-Modul konvertiert, das das geparste Objekt als export default exportiert.

name: John Doe
age: 35
email: johndoe@example.com

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

---

text

Text-Loader. Standard für .txt.

Der Inhalt der Textdatei wird gelesen und als String in das Bundle inline eingefügt. Textdateien können direkt importiert werden. Die Datei wird gelesen und als String zurückgegeben.

import contents from "./file.txt";
console.log(contents); // => "Hello, world!"

// Um eine HTML-Datei als Text zu importieren
// Das "type"-Attribut kann verwendet werden, um den Standard-Loader zu überschreiben.
import html from "./index.html" with { type: "text" };

Wenn während eines Builds referenziert, wird der Inhalt als String in das Bundle inline eingefügt.

var contents = `Hello, world!`;
console.log(contents);

Wenn eine .txt-Datei als Einstiegspunkt übergeben wird, wird sie in ein .js-Modul konvertiert, das den Dateiinhalt als export default exportiert.

Hello, world!

export default "Hello, world!";

---

napi

Native Addon-Loader. Standard für .node.

In der Runtime können native Addons direkt importiert werden.

import addon from "./addon.node";
console.log(addon);

NOTE

Im Bundler werden `.node`-Dateien mit dem Datei-Loader behandelt.

---

sqlite

SQLite-Loader. Erfordert das Importattribut with { "type": "sqlite" }.

In der Runtime und im Bundler können SQLite-Datenbanken direkt importiert werden. Dies lädt die Datenbank mit bun:sqlite.

import db from "./my.db" with { type: "sqlite" };

Standardmäßig ist die Datenbank extern zum Bundle (damit Sie möglicherweise eine anderswo geladene Datenbank verwenden können), sodass die Datenbankdatei auf der Festplatte nicht in die endgültige Ausgabe gebündelt wird.

Sie können dieses Verhalten mit dem "embed"-Attribut ändern:

// Die Datenbank in das Bundle einbetten
import db from "./my.db" with { type: "sqlite", embed: "true" };

---

html

HTML-Loader. Standard für .html.

Der html-Loader verarbeitet HTML-Dateien und bündelt alle referenzierten Assets. Er wird:

• Referenzierte JavaScript-Dateien bündeln und hashen (<script src="...">)
• Referenzierte CSS-Dateien bündeln und hashen (<link rel="stylesheet" href="...">)
• Referenzierte Bilder hashen (<img src="...">)
• Externe URLs beibehalten (standardmäßig alles, was mit http:// oder https:// beginnt)

Zum Beispiel, bei dieser HTML-Datei:

src/index.html

<!DOCTYPE html>
<html>
  <body>
    <img src="./image.jpg" alt="Local image" />
    <img src="https://example.com/image.jpg" alt="External image" />
    <script type="module" src="./script.js"></script>
  </body>
</html>

Er gibt eine neue HTML-Datei mit den gebündelten Assets aus:

dist/index.html

<!DOCTYPE html>
<html>
  <body>
    <img src="./image-HASHED.jpg" alt="Local image" />
    <img src="https://example.com/image.jpg" alt="External image" />
    <script type="module" src="./output-ALSO-HASHED.js"></script>
  </body>
</html>

Unter der Haube verwendet er lol-html, um Script- und Link-Tags als Einstiegspunkte und andere Assets als extern zu extrahieren.

Liste der unterstützten HTML-Selektoren

Derzeit ist die Liste der Selektoren:

• audio[src]
• iframe[src]
• img[src]
• img[srcset]
• link:not([rel~='stylesheet']):not([rel~='modulepreload']):not([rel~='manifest']):not([rel~='icon']):not([rel~='apple-touch-icon'])[href]
• link[as='font'][href], link[type^='font/'][href]
• link[as='image'][href]
• link[as='style'][href]
• link[as='video'][href], link[as='audio'][href]
• link[as='worker'][href]
• link[rel='icon'][href], link[rel='apple-touch-icon'][href]
• link[rel='manifest'][href]
• link[rel='stylesheet'][href]
• script[src]
• source[src]
• source[srcset]
• video[poster]
• video[src]

NOTE

HTML-Loader-Verhalten in verschiedenen Kontexten

Der html-Loader verhält sich unterschiedlich, je nachdem, wie er verwendet wird:

• Statischer Build: Wenn Sie bun build ./index.html ausführen, erstellt Bun eine statische Site mit allen gebündelten und gehashten Assets.
• Runtime: Wenn Sie bun run server.ts ausführen (wobei server.ts eine HTML-Datei importiert), bündelt Bun Assets während der Entwicklung on-the-fly und ermöglicht Funktionen wie Hot Module Replacement.
• Fullstack-Build: Wenn Sie bun build --target=bun server.ts ausführen (wobei server.ts eine HTML-Datei importiert), wird der Import zu einem Manifest-Objekt aufgelöst, das Bun.serve verwendet, um in der Produktion effizient vorgebündelte Assets bereitzustellen.

---

css

CSS-Loader. Standard für .css.

CSS-Dateien können direkt importiert werden. Der Bundler parst und bündelt CSS-Dateien und verarbeitet @import-Anweisungen und url()-Referenzen.

import "./styles.css";

Während des Bündelns werden alle importierten CSS-Dateien zu einer einzigen .css-Datei im Ausgabeverzeichnis gebündelt.

.my-class {
  background: url("./image.png");
}

---

sh

Bun Shell-Loader. Standard für .sh-Dateien.

Dieser Loader wird verwendet, um Bun Shell-Skripte zu parsen. Er wird nur unterstützt, wenn Bun selbst gestartet wird, daher ist er im Bundler oder in der Runtime nicht verfügbar.

bun run ./script.sh

---

file

Datei-Loader. Standard für alle nicht erkannten Dateitypen.

Der Datei-Loader löst den Import als Pfad/URL zur importierten Datei auf. Er wird häufig zum Referenzieren von Medien- oder Schriftart-Assets verwendet.

// logo.ts
import logo from "./logo.svg";
console.log(logo);

In der Runtime prüft Bun, ob die logo.svg-Datei existiert, und konvertiert sie in einen absoluten Pfad zum Speicherort von logo.svg auf der Festplatte.

bun run logo.ts
# Ausgabe: /path/to/project/logo.svg

Im Bundler ist es etwas anders. Die Datei wird unverändert in outdir kopiert, und der Import wird als relativer Pfad zur kopierten Datei aufgelöst.

// Ausgabe
var logo = "./logo.svg";
console.log(logo);

Wenn ein Wert für publicPath angegeben wird, verwendet der Import diesen Wert als Präfix, um einen absoluten Pfad/eine absolute URL zu konstruieren.

Öffentlicher Pfad	Aufgelöster Import
"" (Standard)	/logo.svg
"/assets"	/assets/logo.svg
"https://cdn.example.com/"	https://cdn.example.com/logo.svg

NOTE

Der Speicherort und Dateiname der kopierten Datei wird durch den Wert von `naming.asset` bestimmt.

Dieser Loader wird unverändert in das outdir kopiert. Der Name der kopierten Datei wird mit dem Wert von naming.asset bestimmt.