Der Bun-Bundler implementiert eine Reihe von Standard-Loadern ab Werk. Als Faustregel gilt, dass sowohl der Bundler als auch die Runtime ab Werk dieselben Dateitypen unterstützen.

.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 beim Erstellen von Plugins verwendet, die Bun um benutzerdefinierte Loader erweitern.

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

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

---

Integrierte Loader

js

JavaScript. 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. Standard für .js und .jsx.

Wie der js-Loader, aber JSX-Syntax wird unterstützt. Standardmäßig wird JSX in einfaches JavaScript umgewandelt. Die Details dazu 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 die gesamte 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 zu reinem 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 Bundlings wird das geparste JSON als JavaScript-Objekt in das Bundle eingefügt.

var 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 mit Kommentaren) 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 Bundlings wird das geparste JSONC als JavaScript-Objekt in das Bundle eingefügt, identisch wie der json-Loader.

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

NOTE

Bun verwendet den `jsonc`-Loader automatisch 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 Import-Attribut:
// import myCustomTOML from './my.config' with {type: "toml"};

Während des Bundlings wird das geparste TOML als JavaScript-Objekt in das Bundle 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 Import-Attribut:
import data from "./data.txt" with { type: "yaml" };

Während des Bundlings wird das geparste YAML als JavaScript-Objekt in das Bundle 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 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 darauf verwiesen wird, wird der Inhalt als String in das Bundle 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);

Im Bundler werden .node-Dateien mit dem file-Loader verarbeitet.

sqlite

SQLite-Loader. with { "type": "sqlite" } Import-Attribut

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" };

Dies wird nur unterstützt, wenn das target bun ist.

Standardmäßig ist die Datenbank extern zum Bundle (sodass 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" };

Bei Verwendung eines standalone Executables wird die Datenbank in die Einzeldatei-Executable eingebettet.

Andernfalls wird die einzubettende Datenbank mit einem gehashten Dateinamen in das outdir kopiert.

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:

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

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

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

1. Statischer Build: Wenn Sie bun build ./index.html ausführen, erstellt Bun eine statische Website mit allen gebündelten und gehashten Assets.

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

3. Full-Stack-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. Dies ist hauptsächlich für Full-Stack-Anwendungen nützlich, bei denen CSS zusammen mit HTML gebündelt wird.

import "./styles.css";

Es wird kein Wert vom Import zurückgegeben, er wird nur für Seiteneffekte verwendet.

sh-Loader

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

Dieser Loader wird verwendet, um Bun Shell-Skripte zu parsen. Er wird nur beim Starten von Bun selbst unterstützt und ist daher 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.

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
/path/to/project/logo.svg

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

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`](/bundler#naming) bestimmt.

Dieser Loader wird unverändert in das `outdir` kopiert. Der Name der kopierten Datei wird mithilfe des Werts von `naming.asset` bestimmt.

Beheben von TypeScript-Importfehlern

Wenn Sie TypeScript verwenden, erhalten Sie möglicherweise einen Fehler wie diesen:

// TypeScript-Fehler
// Modul './logo.svg' oder seine entsprechenden Typdeklarationen können nicht gefunden werden.

Dies kann behoben werden, indem Sie eine *.d.ts-Datei irgendwo in Ihrem Projekt erstellen (jeder Name funktioniert) mit dem folgenden Inhalt:

declare module "*.svg" {
  const content: string;
  export default content;
}

Dies teilt TypeScript mit, dass alle Standardimporte von .svg als String behandelt werden sollen.