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 builtin 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 personalizados.

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

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 builtin

js

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

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

Mesmo que o loader js, mas sintaxe JSX é suportada. Por padrão, JSX é convertido 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 é inlineado no bundle como um objeto JavaScript.

var 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 extras.

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

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

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

NOTE

O Bun usa automaticamente 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 analisador 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 é inlineado 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 analisador 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 é inlineado 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 inlineado 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 sobrescrever o loader padrão.
import html from "./index.html" with { type: "text" };

Quando referenciado durante um build, o conteúdo é inlineado 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);

No bundler, arquivos .node são tratados usando o loader file.

sqlite

Loader SQLite. 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" };

Isso é suportado apenas quando o target é bun.

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 do banco de dados no disco não será bundled na saída final.

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

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

Ao usar um executável standalone, o banco de dados é incorporado no executável de arquivo único.

Caso contrário, o banco de dados a incorporar é copiado para o outdir com um nome de arquivo com hash.

html

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

• Bundlar e fazer hash de arquivos JavaScript referenciados (<script src="...">)
• Bundlar e fazer hash de arquivos CSS referenciados (<link rel="stylesheet" href="...">)
• Fazer 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:

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

<!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 extrair tags de script e link como entrypoints, e outros assets como externos.

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:

1. Build Estático: Quando você executa bun build ./index.html, o Bun produz um site estático com todos os assets bundled e com hash.

2. Runtime: Quando você executa bun run server.ts (onde server.ts importa um arquivo HTML), o Bun bundla assets on-the-fly durante o desenvolvimento, habilitando recursos como hot module replacement.

3. 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 de manifesto que Bun.serve usa para servir eficientemente assets pré-bundled em produção.

css

Loader CSS. Padrão para .css.

Arquivos CSS podem ser importados diretamente. Isso é principalmente útil para aplicações full-stack onde CSS é bundled junto com HTML.

import "./styles.css";

Não há nenhum valor retornado do import, é usado apenas para efeitos colaterais.

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

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 no disco.

bun run logo.ts
/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.

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	Import resolvido
"" (padrão)	/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`](/pt/bundler#naming).

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

Corrigindo erros de import do TypeScript

Se você estiver usando TypeScript, pode receber um erro como este:

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

Isso pode ser corrigido criando um arquivo *.d.ts em qualquer lugar do seu projeto (qualquer nome funcionará) com o seguinte conteúdo:

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

Isso diz ao TypeScript que qualquer import default de .svg deve ser tratado como uma string.