El empaquetador de Bun implementa un conjunto de loaders predeterminados integrados.

Como regla general: el empaquetador y el runtime ambos soportan el mismo conjunto de tipos de archivo integrados.

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

Bun usa la extensión del archivo para determinar qué loader integrado debe usarse para analizar el archivo. Cada loader tiene un nombre, como js, tsx, o json. Estos nombres se usan al construir plugins que extienden Bun con loaders personalizados.

Puedes especificar explícitamente qué loader usar usando el atributo de import 'type'.

index.ts

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

Loaders integrados

js

Loader de JavaScript. Predeterminado para .cjs y .mjs.

Analiza el código y aplica un conjunto de transformaciones predeterminadas como eliminación de código muerto y tree shaking. Ten en cuenta que Bun no intenta convertir sintaxis hacia abajo por el momento.

---

jsx

Loader de JavaScript + JSX. Predeterminado para .js y .jsx.

Igual que el loader js, pero se soporta sintaxis JSX. Por defecto, JSX se convierte hacia abajo a JavaScript plano; los detalles de cómo se hace esto dependen de las opciones del compilador jsx* en tu tsconfig.json. Consulta la documentación de TypeScript sobre JSX para más información.

---

ts

Loader de TypeScript. Predeterminado para .ts, .mts, y .cts.

Elimina toda la sintaxis de TypeScript, luego se comporta idénticamente al loader js. Bun no realiza verificación de tipos.

---

tsx

Loader de TypeScript + JSX. Predeterminado para .tsx.

Transpila tanto TypeScript como JSX a JavaScript vanilla.

---

json

Loader de JSON. Predeterminado para .json.

Los archivos JSON pueden importarse directamente.

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

Durante el empaquetado, el JSON analizado se incluye en línea en el bundle como un objeto JavaScript.

const pkg = {
  name: "my-package",
  // ... otros campos
};

pkg.name;

Si se pasa un archivo .json como entrypoint al empaquetador, se convertirá en un módulo .js que hace export default del objeto analizado.

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

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

---

jsonc

Loader de JSON con Comentarios. Predeterminado para .jsonc.

Los archivos JSONC (JSON con Comentarios) pueden importarse directamente. Bun los analizará, eliminando comentarios y comas finales.

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

Durante el empaquetado, el JSONC analizado se incluye en línea en el bundle como un objeto JavaScript, idéntico al loader json.

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

NOTE

Bun usa automáticamente el loader `jsonc` para archivos `tsconfig.json`, `jsconfig.json`, `package.json`, y `bun.lock`.

---

toml

Loader de TOML. Predeterminado para .toml.

Los archivos TOML pueden importarse directamente. Bun los analizará con su rápido analizador TOML nativo.

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

// vía atributo de import:
// import myCustomTOML from './my.config' with {type: "toml"};

Durante el empaquetado, el TOML analizado se incluye en línea en el bundle como un objeto JavaScript.

var config = {
  logLevel: "debug",
  // ...otros campos
};
config.logLevel;

Si se pasa un archivo .toml como entrypoint, se convertirá en un módulo .js que hace export default del objeto analizado.

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

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

---

yaml

Loader de YAML. Predeterminado para .yaml y .yml.

Los archivos YAML pueden importarse directamente. Bun los analizará con su rápido analizador YAML nativo.

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

// vía atributo de import:
import data from "./data.txt" with { type: "yaml" };

Durante el empaquetado, el YAML analizado se incluye en línea en el bundle como un objeto JavaScript.

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

Si se pasa un archivo .yaml o .yml como entrypoint, se convertirá en un módulo .js que hace export default del objeto analizado.

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

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

---

text

Loader de texto. Predeterminado para .txt.

El contenido del archivo de texto se lee e incluye en línea en el bundle como una cadena. Los archivos de texto pueden importarse directamente. El archivo se lee y se devuelve como una cadena.

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

// Para importar un archivo html como texto
// El atributo "type" puede usarse para anular el loader predeterminado.
import html from "./index.html" with { type: "text" };

Cuando se referencia durante una construcción, el contenido se incluye en línea en el bundle como una cadena.

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

Si se pasa un archivo .txt como entrypoint, se convertirá en un módulo .js que hace export default del contenido del archivo.

Hello, world!

export default "Hello, world!";

---

napi

Loader de addon nativo. Predeterminado para .node.

En el runtime, los addons nativos pueden importarse directamente.

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

NOTE

En el empaquetador, los archivos `.node` se manejan usando el file loader.

---

sqlite

Loader de SQLite. Requiere el atributo de import with { "type": "sqlite" }.

En el runtime y empaquetador, las bases de datos SQLite pueden importarse directamente. Esto cargará la base de datos usando bun:sqlite.

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

Por defecto, la base de datos es externa al bundle (para que potencialmente puedas usar una base de datos cargada en otro lugar), por lo que el archivo de base de datos en disco no se empaquetará en la salida final.

Puedes cambiar este comportamiento con el atributo "embed":

// incrustar la base de datos en el bundle
import db from "./my.db" with { type: "sqlite", embed: "true" };

---

html

Loader de HTML. Predeterminado para .html.

El loader html procesa archivos HTML y empaqueta cualquier asset referenciado. Hará:

• Empaquetar y hashear archivos JavaScript referenciados (<script src="...">)
• Empaquetar y hashear archivos CSS referenciados (<link rel="stylesheet" href="...">)
• Hashear imágenes referenciadas (<img src="...">)
• Preservar URLs externas (por defecto, cualquier cosa que comience con http:// o https://)

Por ejemplo, dado este archivo HTML:

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>

Generará un nuevo archivo HTML con los assets empaquetados:

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>

Internamente, usa lol-html para extraer etiquetas script y link como entrypoints, y otros assets como externos.

Lista de selectores HTML soportados">

Actualmente, la lista de selectores es:

• 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

Comportamiento del Loader HTML en Diferentes Contextos

El loader html se comporta de manera diferente dependiendo de cómo se use:

• Construcción Estática: Cuando ejecutas bun build ./index.html, Bun produce un sitio estático con todos los assets empaquetados y hasheados.
• Runtime: Cuando ejecutas bun run server.ts (donde server.ts importa un archivo HTML), Bun empaqueta assets sobre la marcha durante el desarrollo, habilitando características como reemplazo de módulos en caliente.
• Construcción Full-stack: Cuando ejecutas bun build --target=bun server.ts (donde server.ts importa un archivo HTML), el import se resuelve a un objeto manifiesto que Bun.serve usa para servir eficientemente assets pre-empaquetados en producción.

---

css

Loader de CSS. Predeterminado para .css.

Los archivos CSS pueden importarse directamente. El empaquetador analizará y empaquetará archivos CSS, manejando declaraciones @import y referencias url().

import "./styles.css";

Durante el empaquetado, todos los archivos CSS importados se empaquetan juntos en un único archivo .css en el directorio de salida.

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

---

sh

Loader de Bun Shell. Predeterminado para archivos .sh.

Este loader se usa para analizar scripts de Bun Shell. Solo se soporta al iniciar Bun mismo, por lo que no está disponible en el empaquetador o en el runtime.

bun run ./script.sh

---

file

File loader. Predeterminado para todos los tipos de archivo no reconocidos.

El file loader resuelve el import como una ruta/URL al archivo importado. Comúnmente se usa para referenciar assets de medios o fuentes.

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

En el runtime, Bun verifica que el archivo logo.svg exista y lo convierte a una ruta absoluta a la ubicación de logo.svg en disco.

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

En el empaquetador, las cosas son ligeramente diferentes. El archivo se copia en outdir tal cual, y el import se resuelve como una ruta relativa que apunta al archivo copiado.

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

Si se especifica un valor para publicPath, el import usará ese valor como prefijo para construir una ruta/URL absoluta.

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

NOTE

La ubicación y nombre del archivo copiado se determina por el valor de `naming.asset`.

Este loader se copia en el outdir tal cual. El nombre del archivo copiado se determina usando el valor de naming.asset.