Le bundler de Bun implémente un ensemble de loaders par défaut.

En règle générale : le bundler et le runtime prennent tous deux en charge le même ensemble de types de fichiers nativement.

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

Bun utilise l'extension de fichier pour déterminer quel loader intégré doit être utilisé pour analyser le fichier. Chaque loader a un nom, tel que js, tsx ou json. Ces noms sont utilisés lors de la création de plugins qui étendent Bun avec des loaders personnalisés.

Vous pouvez explicitement spécifier quel loader utiliser en utilisant l'attribut d'importation 'type'.

import my_toml from "./my_file" with { type: "toml" };
// ou avec des importations dynamiques
const { default: my_toml } = await import("./my_file", { with: { type: "toml" } });

Loaders intégrés

js

Loader JavaScript. Par défaut pour .cjs et .mjs.

Analyse le code et applique un ensemble de transformations par défaut comme l'élimination du code mort et le tree shaking. Notez que Bun n'essaie pas de rétrograder la syntaxe pour le moment.

---

jsx

Loader JavaScript + JSX. Par défaut pour .js et .jsx.

Identique au loader js, mais la syntaxe JSX est prise en charge. Par défaut, JSX est rétrogradé en JavaScript pur ; les détails de la façon dont cela est fait dépendent des options de compilation jsx* dans votre tsconfig.json. Consultez la documentation TypeScript sur JSX pour plus d'informations.

---

ts

Loader TypeScript. Par défaut pour .ts, .mts et .cts.

Supprime toute la syntaxe TypeScript, puis se comporte de manière identique au loader js. Bun n'effectue pas de vérification de type.

---

tsx

Loader TypeScript + JSX. Par défaut pour .tsx.

Transpile à la fois TypeScript et JSX en JavaScript vanilla.

---

json

Loader JSON. Par défaut pour .json.

Les fichiers JSON peuvent être directement importés.

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

Pendant le bundling, le JSON analysé est intégré dans le bundle en tant qu'objet JavaScript.

const pkg = {
  name: "my-package",
  // ... autres champs
};

pkg.name;

Si un fichier .json est passé comme point d'entrée au bundler, il sera converti en un module .js qui export default l'objet analysé.

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

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

---

jsonc

Loader JSON avec commentaires. Par défaut pour .jsonc.

Les fichiers JSONC (JSON avec commentaires) peuvent être directement importés. Bun les analysera, en supprimant les commentaires et les virgules finales.

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

Pendant le bundling, le JSONC analysé est intégré dans le bundle en tant qu'objet JavaScript, identique au loader json.

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

NOTE

Bun utilise automatiquement le loader `jsonc` pour les fichiers `tsconfig.json`, `jsconfig.json`, `package.json` et `bun.lock`.

---

toml

Loader TOML. Par défaut pour .toml.

Les fichiers TOML peuvent être directement importés. Bun les analysera avec son analyseur TOML natif rapide.

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

// via l'attribut d'importation :
// import myCustomTOML from './my.config' with {type: "toml"};

Pendant le bundling, le TOML analysé est intégré dans le bundle en tant qu'objet JavaScript.

var config = {
  logLevel: "debug",
  // ...autres champs
};
config.logLevel;

Si un fichier .toml est passé comme point d'entrée, il sera converti en un module .js qui export default l'objet analysé.

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

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

---

yaml

Loader YAML. Par défaut pour .yaml et .yml.

Les fichiers YAML peuvent être directement importés. Bun les analysera avec son analyseur YAML natif rapide.

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

// via l'attribut d'importation :
import data from "./data.txt" with { type: "yaml" };

Pendant le bundling, le YAML analysé est intégré dans le bundle en tant qu'objet JavaScript.

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

Si un fichier .yaml ou .yml est passé comme point d'entrée, il sera converti en un module .js qui export default l'objet analysé.

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

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

---

text

Loader de texte. Par défaut pour .txt.

Le contenu du fichier texte est lu et intégré dans le bundle en tant que chaîne. Les fichiers texte peuvent être directement importés. Le fichier est lu et retourné en tant que chaîne.

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

// Pour importer un fichier html en tant que texte
// L'attribut "type" peut être utilisé pour remplacer le loader par défaut.
import html from "./index.html" with { type: "text" };

Lorsqu'il est référencé pendant une construction, le contenu est intégré dans le bundle en tant que chaîne.

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

Si un fichier .txt est passé comme point d'entrée, il sera converti en un module .js qui export default le contenu du fichier.

Hello, world!

export default "Hello, world!";

---

napi

Loader d'addon natif. Par défaut pour .node.

Dans le runtime, les addons natifs peuvent être directement importés.

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

NOTE

Dans le bundler, les fichiers `.node` sont gérés via le loader de fichiers.

---

sqlite

Loader SQLite. Nécessite l'attribut d'importation with { "type": "sqlite" }.

Dans le runtime et le bundler, les bases de données SQLite peuvent être directement importées. Cela chargera la base de données en utilisant bun:sqlite.

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

Par défaut, la base de données est externe au bundle (afin que vous puissiez potentiellement utiliser une base de données chargée ailleurs), donc le fichier de base de données sur le disque ne sera pas intégré dans la sortie finale.

Vous pouvez modifier ce comportement avec l'attribut "embed" :

// intégrer la base de données dans le bundle
import db from "./my.db" with { type: "sqlite", embed: "true" };

---

html

Loader HTML. Par défaut pour .html.

Le loader html traite les fichiers HTML et bundle tous les assets référencés. Il va :

• Bundler et hacher les fichiers JavaScript référencés (<script src="...">)
• Bundler et hacher les fichiers CSS référencés (<link rel="stylesheet" href="...">)
• Hacher les images référencées (<img src="...">)
• Préserver les URL externes (par défaut, tout ce qui commence par http:// ou https://)

Par exemple, étant donné ce fichier HTML :

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

Il produira un nouveau fichier HTML avec les assets bundle :

<!DOCTYPE html>
<html>
  <body>
    <img src="./image-HASHED.jpg" alt="Image locale" />
    <img src="https://example.com/image.jpg" alt="Image externe" />
    <script type="module" src="./output-AUSSI-HASHED.js"></script>
  </body>
</html>

Sous le capot, il utilise lol-html pour extraire les balises de script et de lien comme points d'entrée, et d'autres assets comme externes.

Liste des sélecteurs HTML pris en charge

Actuellement, la liste des sélecteurs est :

• 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

Comportement du loader HTML dans différents contextes

Le loader html se comporte différemment selon la façon dont il est utilisé :

• Construction statique : Lorsque vous exécutez bun build ./index.html, Bun produit un site statique avec tous les assets bundle et hachés.
• Runtime : Lorsque vous exécutez bun run server.ts (où server.ts importe un fichier HTML), Bun bundle les assets à la volée pendant le développement, permettant des fonctionnalités comme le remplacement de module à chaud.
• Construction full-stack : Lorsque vous exécutez bun build --target=bun server.ts (où server.ts importe un fichier HTML), l'importation se résout en un objet manifeste que Bun.serve utilise pour servir efficacement des assets pré-bundle en production.

---

css

Loader CSS. Par défaut pour .css.

Les fichiers CSS peuvent être directement importés. Le bundler analysera et bundle les fichiers CSS, gérant les instructions @import et les références url().

import "./styles.css";

Pendant le bundling, tous les fichiers CSS importés sont bundle ensemble dans un seul fichier .css dans le répertoire de sortie.

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

---

sh

Loader Bun Shell. Par défaut pour les fichiers .sh.

Ce loader est utilisé pour analyser les scripts Bun Shell. Il est uniquement pris en charge lors du démarrage de Bun lui-même, donc il n'est pas disponible dans le bundler ou dans le runtime.

bun run ./script.sh

---

file

Loader de fichiers. Par défaut pour tous les types de fichiers non reconnus.

Le loader de fichiers résout l'importation comme un chemin/URL vers le fichier importé. Il est couramment utilisé pour référencer des assets multimédias ou de police.

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

Dans le runtime, Bun vérifie que le fichier logo.svg existe et le convertit en un chemin absolu vers l'emplacement de logo.svg sur le disque.

bun run logo.ts
# Sortie : /chemin/vers/projet/logo.svg

Dans le bundler, les choses sont légèrement différentes. Le fichier est copié dans outdir tel quel, et l'importation est résolue comme un chemin relatif pointant vers le fichier copié.

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

Si une valeur est spécifiée pour publicPath, l'importation utilisera cette valeur comme préfixe pour construire un chemin/URL absolu.

Chemin public	Importation résolue
"" (par défaut)	/logo.svg
"/assets"	/assets/logo.svg
"https://cdn.example.com/"	https://cdn.example.com/logo.svg

NOTE

L'emplacement et le nom du fichier copié sont déterminés par la valeur de `naming.asset`.

Ce loader est copié dans le outdir tel quel. Le nom du fichier copié est déterminé en utilisant la valeur de naming.asset.