Il bundler di Bun implementa un set di loader predefiniti out of the box. Come regola generale, sia il bundler che il runtime supportano lo stesso set di tipi di file out of the box.

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

Bun usa l'estensione del file per determinare quale loader built-in dovrebbe essere usato per parsare il file. Ogni loader ha un nome, come js, tsx, o json. Questi nomi sono usati quando si costruiscono plugin che estendono Bun con loader personalizzati.

Puoi specificare esplicitamente quale loader usare usando l'attributo di import 'type'.

import my_toml from "./my_file" with { type: "toml" };
// o con import dinamici
const { default: my_toml } = await import("./my_file", { with: { type: "toml" } });

---

Loader built-in

js

JavaScript. Predefinito per .cjs e .mjs.

Parsa il codice e applica un set di trasformazioni predefinite come l'eliminazione del codice morto e il tree shaking. Nota che Bun non tenta di down-convertire la sintassi al momento.

jsx

JavaScript + JSX. Predefinito per .js e .jsx.

Come il loader js, ma la sintassi JSX è supportata. Di default, JSX viene down-convertito in JavaScript puro; i dettagli di come questo viene fatto dipendono dalle opzioni del compilatore jsx* nel tuo tsconfig.json. Fai riferimento alla documentazione TypeScript su JSX per maggiori informazioni.

ts

Loader TypeScript. Predefinito per .ts, .mts, e .cts.

Rimuove tutta la sintassi TypeScript, poi si comporta in modo identico al loader js. Bun non esegue typechecking.

tsx

Loader TypeScript + JSX. Predefinito per .tsx. Transpila sia TypeScript che JSX in JavaScript vanilla.

json

Loader JSON. Predefinito per .json.

I file JSON possono essere importati direttamente.

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

Durante il bundling, il JSON parsato viene inlinato nel bundle come un oggetto JavaScript.

var pkg = {
  name: "my-package",
  // ... altri campi
};
pkg.name;

Se un file .json viene passato come entrypoint al bundler, verrà convertito in un modulo .js che fa export default dell'oggetto parsato.

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

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

jsonc

Loader JSON con Commenti. Predefinito per .jsonc.

I file JSONC (JSON with Comments) possono essere importati direttamente. Bun li parserà, rimuovendo commenti e virgole finali.

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

Durante il bundling, il JSONC parsato viene inlinato nel bundle come un oggetto JavaScript, identico al loader json.

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

NOTE

Bun usa automaticamente il loader `jsonc` per i file `tsconfig.json`, `jsconfig.json`, `package.json`, e `bun.lock`.

toml

Loader TOML. Predefinito per .toml.

I file TOML possono essere importati direttamente. Bun li parserà con il suo veloce parser TOML nativo.

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

// tramite attributo di import:
// import myCustomTOML from './my.config' with {type: "toml"};

Durante il bundling, il TOML parsato viene inlinato nel bundle come un oggetto JavaScript.

var config = {
  logLevel: "debug",
  // ...altri campi
};
config.logLevel;

Se un file .toml viene passato come entrypoint, verrà convertito in un modulo .js che fa export default dell'oggetto parsato.

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

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

yaml

Loader YAML. Predefinito per .yaml e .yml.

I file YAML possono essere importati direttamente. Bun li parserà con il suo veloce parser YAML nativo.

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

// tramite attributo di import:
import data from "./data.txt" with { type: "yaml" };

Durante il bundling, il YAML parsato viene inlinato nel bundle come un oggetto JavaScript.

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

Se un file .yaml o .yml viene passato come entrypoint, verrà convertito in un modulo .js che fa export default dell'oggetto parsato.

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

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

text

Loader testo. Predefinito per .txt.

I contenuti del file di testo vengono letti e inlinati nel bundle come una stringa. I file di testo possono essere importati direttamente. Il file viene letto e restituito come una stringa.

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

// Per importare un file html come testo
// L'attributo "type" può essere usato per sovrascrivere il loader predefinito.
import html from "./index.html" with { type: "text" };

Quando referenziato durante una build, i contenuti vengono inlinati nel bundle come una stringa.

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

Se un file .txt viene passato come entrypoint, verrà convertito in un modulo .js che fa export default dei contenuti del file.

Hello, world!

export default "Hello, world!";

napi

Loader addon nativo. Predefinito per .node.

Nel runtime, gli addon nativi possono essere importati direttamente.

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

Nel bundler, i file .node sono gestiti usando il loader file.

sqlite

Loader SQLite. Attributo di import with { "type": "sqlite" }

Nel runtime e bundler, i database SQLite possono essere importati direttamente. Questo caricherà il database usando bun:sqlite.

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

Questo è supportato solo quando il target è bun.

Di default, il database è esterno al bundle (così puoi potenzialmente usare un database caricato altrove), quindi il file del database su disco non verrà bundlato nell'output finale.

Puoi cambiare questo comportamento con l'attributo "embed":

// embedda il database nel bundle
import db from "./my.db" with { type: "sqlite", embed: "true" };

Quando si usa un eseguibile standalone, il database viene embeddato nell'eseguibile single-file.

Altrimenti, il database da embeddare viene copiato nella outdir con un nome file hashato.

html

Il loader html processa i file HTML e bundla qualsiasi asset referenziato. Farà:

• Bundle e hash dei file JavaScript referenziati (<script src="...">)
• Bundle e hash dei file CSS referenziati (<link rel="stylesheet" href="...">)
• Hash delle immagini referenziate (<img src="...">)
• Preserva gli URL esterni (di default, qualsiasi cosa che inizia con http:// o https://)

Per esempio, dato questo file 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>

Produrrà un nuovo file HTML con gli asset bundlati:

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

Sotto il cofano, usa lol-html per estrarre script e tag link come entrypoint, e altri asset come esterni.

Attualmente, la lista di selettori è:

• 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

Comportamento dell'HTML Loader in Contesti Diversi

Il loader html si comporta in modo diverso a seconda di come viene usato:

1. Build Statica: Quando esegui bun build ./index.html, Bun produce un sito statico con tutti gli asset bundlati e hashati.

2. Runtime: Quando esegui bun run server.ts (dove server.ts importa un file HTML), Bun bundla gli asset on-the-fly durante lo sviluppo, abilitando funzionalità come l'hot module replacement.

3. Build Full-stack: Quando esegui bun build --target=bun server.ts (dove server.ts importa un file HTML), l'import risolve in un oggetto manifest che Bun.serve usa per servire efficientemente gli asset pre-bundlati in produzione.

css

Loader CSS. Predefinito per .css.

I file CSS possono essere importati direttamente. Questo è principalmente utile per applicazioni full-stack dove il CSS viene bundlato insieme all'HTML.

import "./styles.css";

Non c'è alcun valore restituito dall'import, viene usato solo per gli effetti collaterali.

Loader sh

Loader Bun Shell. Predefinito per i file .sh

Questo loader è usato per parsare script Bun Shell. È supportato solo quando si avvia Bun stesso, quindi non è disponibile nel bundler o nel runtime.

bun run ./script.sh

file

Loader file. Predefinito per tutti i tipi di file non riconosciuti.

Il loader file risolve l'import come un percorso/URL al file importato. È comunemente usato per referenziare asset media o font.

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

Nel runtime, Bun controlla che il file logo.svg esista e lo converte in un percorso assoluto alla posizione di logo.svg su disco.

bun run logo.ts
/percorso/al/progetto/logo.svg

Nel bundler, le cose sono leggermente diverse. Il file viene copiato in outdir così com'è, e l'import è risolto come un percorso relativo che punta al file copiato.

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

Se un valore è specificato per publicPath, l'import userà quel valore come prefisso per costruire un percorso/URL assoluto.

Public path	Import risolto
"" (default)	/logo.svg
"/assets"	/assets/logo.svg
"https://cdn.example.com/"	https://cdn.example.com/logo.svg

NOTE

La posizione e il nome del file copiato è determinato dal valore di [`naming.asset`](/bundler#naming).

Questo loader viene copiato in `outdir` così com'è. Il nome del file copiato è determinato usando il valore di `naming.asset`.

Correggere gli errori di import di TypeScript">

Se stai usando TypeScript, potresti ottenere un errore come questo:

// Errore TypeScript
// Cannot find module './logo.svg' or its corresponding type declarations.

Questo può essere corretto creando un file *.d.ts ovunque nel tuo progetto (qualsiasi nome funzionerà) con i seguenti contenuti:

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

Questo dice a TypeScript che qualsiasi import default da .svg dovrebbe essere trattato come una stringa.