O bundler do Bun implementa um conjunto de loaders padrão prontos para uso.

Como regra geral: o bundler e o runtime suportam o mesmo conjunto de tipos de arquivo prontos para uso.

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

O Bun usa a extensão do arquivo para determinar qual loader built-in deve ser usado para analisar o arquivo. Cada loader tem um nome, como js, tsx ou json. Estes nomes são usados ao construir plugins que estendem o Bun com loaders customizados.

Você pode especificar explicitamente qual loader usar usando o atributo de import 'type'.

index.ts

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

Loaders built-in

js

Loader JavaScript. Padrão para .cjs e .mjs.

Analisa o código e aplica um conjunto de transformações padrão como eliminação de código morto e tree shaking. Note que o Bun não tenta fazer down-convert de sintaxe no momento.

---

jsx

Loader JavaScript + JSX. Padrão para .js e .jsx.

Mesmo que o loader js, mas sintaxe JSX é suportada. Por padrão, JSX é down-convert para JavaScript puro; os detalhes de como isso é feito dependem das opções de compilação jsx* no seu tsconfig.json. Consulte a documentação do TypeScript sobre JSX para mais informações.

---

ts

Loader TypeScript. Padrão para .ts, .mts e .cts.

Remove toda sintaxe TypeScript, depois se comporta identicamente ao loader js. O Bun não realiza verificação de tipos.

---

tsx

Loader TypeScript + JSX. Padrão para .tsx.

Transpila tanto TypeScript quanto JSX para JavaScript puro.

---

json

Loader JSON. Padrão para .json.

Arquivos JSON podem ser importados diretamente.

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

Durante o bundling, o JSON analisado é inline no bundle como um objeto JavaScript.

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

pkg.name;

Se um arquivo .json for passado como entrypoint para o bundler, ele será convertido para um módulo .js que faz export default do objeto analisado.

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

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

---

jsonc

Loader JSON com Comentários. Padrão para .jsonc.

Arquivos JSONC (JSON com Comentários) podem ser importados diretamente. O Bun os analisará, removendo comentários e vírgulas à direita.

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

Durante o bundling, o JSONC analisado é inline no bundle como um objeto JavaScript, idêntico ao loader json.

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

NOTE

O Bun automaticamente usa o loader `jsonc` para arquivos `tsconfig.json`, `jsconfig.json`, `package.json` e `bun.lock`.

---

toml

Loader TOML. Padrão para .toml.

Arquivos TOML podem ser importados diretamente. O Bun os analisará com seu parser TOML nativo rápido.

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

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

Durante o bundling, o TOML analisado é inline no bundle como um objeto JavaScript.

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

Se um arquivo .toml for passado como entrypoint, ele será convertido para um módulo .js que faz export default do objeto analisado.

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

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

---

yaml

Loader YAML. Padrão para .yaml e .yml.

Arquivos YAML podem ser importados diretamente. O Bun os analisará com seu parser YAML nativo rápido.

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

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

Durante o bundling, o YAML analisado é inline no bundle como um objeto JavaScript.

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

Se um arquivo .yaml ou .yml for passado como entrypoint, ele será convertido para um módulo .js que faz export default do objeto analisado.

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

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

---

text

Loader de texto. Padrão para .txt.

O conteúdo do arquivo de texto é lido e inline no bundle como uma string. Arquivos de texto podem ser importados diretamente. O arquivo é lido e retornado como uma string.

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

// Para importar um arquivo html como texto
// O atributo "type" pode ser usado para substituir o loader padrão.
import html from "./index.html" with { type: "text" };

Quando referenciado durante um build, o conteúdo é inline no bundle como uma string.

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

Se um arquivo .txt for passado como entrypoint, ele será convertido para um módulo .js que faz export default do conteúdo do arquivo.

Hello, world!

export default "Hello, world!";

---

napi

Loader de addon nativo. Padrão para .node.

No runtime, addons nativos podem ser importados diretamente.

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

NOTE

No bundler, arquivos `.node` são manipulados usando o loader de arquivo.

---

sqlite

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

No runtime e bundler, bancos de dados SQLite podem ser importados diretamente. Isso carregará o banco de dados usando bun:sqlite.

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

Por padrão, o banco de dados é externo ao bundle (para que você possa potencialmente usar um banco de dados carregado em outro lugar), então o arquivo de banco de dados em disco não será empacotado no output final.

Você pode mudar este comportamento com o atributo "embed":

// embed o banco de dados no bundle
import db from "./my.db" with { type: "sqlite", embed: "true" };

---

html

Loader HTML. Padrão para .html.

O loader html processa arquivos HTML e empacota quaisquer assets referenciados. Ele irá:

• Empacotar e gerar hash de arquivos JavaScript referenciados (<script src="...">)
• Empacotar e gerar hash de arquivos CSS referenciados (<link rel="stylesheet" href="...">)
• Gerar hash de imagens referenciadas (<img src="...">)
• Preservar URLs externas (por padrão, qualquer coisa começando com http:// ou https://)

Por exemplo, dado este arquivo 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>

Ele produzirá um novo arquivo HTML com os assets empacotados:

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>

Por baixo dos panos, usa lol-html para extrair tags script e link como entrypoints e outros assets como externos.

Lista de seletores HTML suportados

Atualmente, a lista de seletores é:

• 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 do Loader HTML em Diferentes Contextos

O loader html se comporta de maneira diferente dependendo de como é usado:

• Build Estático: Quando você executa bun build ./index.html, o Bun produz um site estático com todos os assets empacotados e com hash.
• Runtime: Quando você executa bun run server.ts (onde server.ts importa um arquivo HTML), o Bun empacota assets on-the-fly durante o desenvolvimento, habilitando recursos como hot module replacement.
• Build Full-stack: Quando você executa bun build --target=bun server.ts (onde server.ts importa um arquivo HTML), o import resolve para um objeto manifest que Bun.serve usa para servir eficientemente assets pré-empacotados em produção.

---

css

Loader CSS. Padrão para .css.

Arquivos CSS podem ser importados diretamente. O bundler analisará e empacotará arquivos CSS, lidando com declarações @import e referências url().

import "./styles.css";

Durante o bundling, todos os arquivos CSS importados são empacotados juntos em um único arquivo .css no diretório de output.

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

---

sh

Loader Bun Shell. Padrão para arquivos .sh.

Este loader é usado para analisar scripts Bun Shell. É suportado apenas ao iniciar o próprio Bun, então não está disponível no bundler ou no runtime.

bun run ./script.sh

---

file

Loader de arquivo. Padrão para todos os tipos de arquivo não reconhecidos.

O loader de arquivo resolve o import como um caminho/URL para o arquivo importado. É comumente usado para referenciar assets de mídia ou fonte.

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

No runtime, o Bun verifica se o arquivo logo.svg existe e o converte para um caminho absoluto para a localização de logo.svg em disco.

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

No bundler, as coisas são ligeiramente diferentes. O arquivo é copiado para outdir como está, e o import é resolvido como um caminho relativo apontando para o arquivo copiado.

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

Se um valor for especificado para publicPath, o import usará o valor como prefixo para construir um caminho/URL absoluto.

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

NOTE

A localização e nome do arquivo copiado é determinado pelo valor de `naming.asset`.

Este loader é copiado para o outdir como está. O nome do arquivo copiado é determinado usando o valor de naming.asset.