HTML & sites estáticos Bun JS

O bundler do Bun tem suporte de primeira classe para HTML. Construa sites estáticos, landing pages e aplicações web com zero configuração. Basta apontar o Bun para seu arquivo HTML e ele cuida de tudo mais.

html

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="./styles.css" />
    <script src="./app.ts" type="module"></script>
  </head>
  <body>
    <img src="./logo.png" />
  </body>
</html>

Para começar, passe arquivos HTML para o bun.

bash

bun ./index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

O servidor de desenvolvimento do Bun fornece recursos poderosos com zero configuração:

Bundling Automático - Empacota e serve seu HTML, JavaScript e CSS
Suporte Multi-Entry - Lida com múltiplos entry points HTML e glob entry points
JavaScript Moderno - Suporte nativo para TypeScript e JSX
Configuração Inteligente - Lê tsconfig.json para paths, opções JSX, decorators experimentais e mais
Plugins - Plugins para TailwindCSS e mais
ESM e CommonJS - Use ESM e CommonJS em seus arquivos JavaScript, TypeScript e JSX
Bundling e Minificação de CSS - Empacota CSS de tags <link> e declarações @import
Gerenciamento de Assets - Cópia e hashing automático de imagens e assets; Reescreve caminhos de assets em JavaScript, CSS e HTML

Single Page Apps (SPA)

Quando você passa um único arquivo .html para o Bun, o Bun o usará como uma rota fallback para todos os caminhos. Isso o torna perfeito para single page apps que usam roteamento do lado do cliente:

bash

bun index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

Seu React ou outra SPA funcionará imediatamente — sem configuração necessária. Todas as rotas como /about, /users/123, etc. servirão o mesmo arquivo HTML, permitindo que seu roteador do lado do cliente lide com a navegação.

html

<!doctype html>
<html>
  <head>
    <title>My SPA</title>
    <script src="./app.tsx" type="module"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

Multi-page apps (MPA)

Alguns projetos têm várias rotas separadas ou arquivos HTML como entry points. Para suportar múltiplos entry points, passe todos eles para o bun:

bash

bun ./index.html ./about.html

txt

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about.html
Press h + Enter to show shortcuts

Isso servirá:

index.html em /
about.html em /about

Padrões glob

Para especificar múltiplos arquivos, você pode usar padrões glob que terminam em .html:

bash

bun ./**/*.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about.html
Press h + Enter to show shortcuts

Normalização de caminho

O caminho base é escolhido a partir do prefixo comum mais longo entre todos os arquivos.

bash

bun ./index.html ./about/index.html ./about/foo/index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about/index.html
  /about/foo ./about/foo/index.html
Press h + Enter to show shortcuts

JavaScript, TypeScript e JSX

O transpiler do Bun implementa nativamente suporte para JavaScript, TypeScript e JSX. Saiba mais sobre loaders no Bun.

NOTE

O transpiler do Bun também é usado em runtime.

ES Modules e CommonJS

Você pode usar ESM e CJS em seus arquivos JavaScript, TypeScript e JSX. O Bun lidará com a transpilação e bundling automaticamente.

Não há pré-build ou etapa de otimização separada. Tudo é feito ao mesmo tempo.

Saiba mais sobre resolução de módulos no Bun.

CSS

O parser CSS do Bun também é implementado nativamente (com cerca de 58.000 linhas de Zig).

Também é um bundler CSS. Você pode usar @import em seus arquivos CSS para importar outros arquivos CSS.

Por exemplo:

css

@import "./abc.css";

.container {
  background-color: blue;
}

css

body {
  background-color: red;
}

Isso produz:

css

body {
  background-color: red;
}

.container {
  background-color: blue;
}

Referenciando assets locais em CSS

Você pode referenciar assets locais em seus arquivos CSS.

css

body {
  background-image: url("./logo.png");
}

Isso copiará ./logo.png para o diretório de output e reescreverá o caminho no arquivo CSS para incluir um hash de conteúdo.

css

body {
  background-image: url("./logo-[ABC123].png");
}

Importando CSS em JavaScript

Para associar um arquivo CSS com um arquivo JavaScript, você pode importá-lo em seu arquivo JavaScript.

import "./styles.css";
import "./more-styles.css";

Isso gera ./app.css e ./app.js no diretório de output. Todos os arquivos CSS importados do JavaScript serão empacotados em um único arquivo CSS por entry point. Se você importar o mesmo arquivo CSS de múltiplos arquivos JavaScript, ele será incluído apenas uma vez no arquivo CSS de output.

Plugins

O servidor de desenvolvimento suporta plugins.

Tailwind CSS

Para usar TailwindCSS, instale o plugin bun-plugin-tailwind:

bash

# Ou qualquer cliente npm
bun install --dev bun-plugin-tailwind

Então, adicione o plugin ao seu bunfig.toml:

bunfig.toml

toml

[serve.static]
plugins = ["bun-plugin-tailwind"]

Então, referencie TailwindCSS em seu HTML via tag <link>, @import em CSS ou import em JavaScript.

html

<!-- Referencie TailwindCSS em seu HTML -->
<link rel="stylesheet" href="tailwindcss" />

styles.css

css

@import "tailwindcss";

import "tailwindcss";

Variáveis de ambiente inline

O Bun pode substituir referências process.env.* em seu JavaScript e TypeScript com seus valores reais em tempo de build. Isso é útil para injetar configuração como URLs de API ou feature flags em seu código frontend.

Servidor de desenvolvimento (runtime)

Para inline variáveis de ambiente ao usar bun ./index.html, configure a opção env em seu bunfig.toml:

bunfig.toml

toml

[serve.static]
env = "PUBLIC_*"  # apenas inline env vars começando com PUBLIC_ (recomendado)
# env = "inline"  # inline todas as variáveis de ambiente
# env = "disable" # desabilita substituição de env var (padrão)

NOTE

Isso funciona apenas com referências literais `process.env.FOO`, não `import.meta.env` ou acesso indireto como `const env = process.env; env.FOO`.

Se uma variável de ambiente não estiver definida, você pode ver erros de runtime como ReferenceError: process is not defined no navegador.

Então execute o servidor de desenvolvimento:

bash

PUBLIC_API_URL=https://api.example.com bun ./index.html

Build para produção

Ao buildar HTML estático para produção, use a opção env para inline variáveis de ambiente:

bash

# Inline todas as variáveis de ambiente
bun build ./index.html --outdir=dist --env=inline

# Apenas inline env vars com um prefixo específico (recomendado)
bun build ./index.html --outdir=dist --env=PUBLIC_*

// Inline todas as variáveis de ambiente
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "inline", 
});

// Apenas inline env vars com um prefixo específico (recomendado)
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "PUBLIC_*", 
});

Exemplo

Dado este arquivo fonte:

const apiUrl = process.env.PUBLIC_API_URL;
console.log(`API URL: ${apiUrl}`);

E executando com PUBLIC_API_URL=https://api.example.com:

bash

PUBLIC_API_URL=https://api.example.com bun build ./index.html --outdir=dist --env=PUBLIC_*

O output empacotado conterá:

dist/app.js

const apiUrl = "https://api.example.com";
console.log(`API URL: ${apiUrl}`);

Ecoar logs de console do navegador para o terminal

O servidor de desenvolvimento do Bun suporta streaming de logs de console do navegador para o terminal.

Para habilitar, passe a flag --console na CLI.

bash

bun ./index.html --console

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

Cada chamada para console.log ou console.error será transmitida para o terminal que iniciou o servidor. Isso é útil para ver erros do navegador no mesmo local onde você executa seu servidor. Isso também é útil para agentes de IA que observam a saída do terminal.

Internamente, isso reusa a conexão WebSocket existente do hot module reloading para enviar os logs.

Editar arquivos no navegador

O servidor de desenvolvimento frontend do Bun tem suporte para Automatic Workspace Folders no Chrome DevTools, que permite salvar edições de arquivos no navegador.

Atalhos de Teclado

Enquanto o servidor está executando:

o + Enter - Abrir no navegador
c + Enter - Limpar console
q + Enter (ou Ctrl+C) - Sair do servidor

Build para Produção

Quando estiver pronto para fazer deploy, use bun build para criar bundles de produção otimizados:

bash

bun build ./index.html --minify --outdir=dist

await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  minify: true,
});

Watch Mode

Você pode executar bun build --watch para observar mudanças e rebuild automaticamente. Isso funciona bem para desenvolvimento de bibliotecas.

API de Plugin

Precisa de mais controle? Configure o bundler através da API JavaScript e use o HTMLRewriter built-in do Bun para pré-processar HTML.

await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  minify: true,

  plugins: [
    {
      // Um plugin que torna todas as tags HTML minúsculas
      name: "lowercase-html-plugin",
      setup({ onLoad }) {
        const rewriter = new HTMLRewriter().on("*", {
          element(element) {
            element.tagName = element.tagName.toLowerCase();
          },
          text(element) {
            element.replace(element.text.toLowerCase());
          },
        });

        onLoad({ filter: /\.html$/ }, async args => {
          const html = await Bun.file(args.path).text();

          return {
            // O bundler do Bun escaneará o HTML por tags <script>, tags <link rel="stylesheet"> e outros assets
            // e os empacotará automaticamente
            contents: rewriter.transform(html),
            loader: "html",
          };
        });
      },
    },
  ],
});

O Que é Processado?

O Bun automaticamente lida com todos os assets web comuns:

Scripts (<script src>) são executados através do bundler JavaScript/TypeScript/JSX do Bun
Stylesheets (<link rel="stylesheet">) são executados através do parser e bundler CSS do Bun
Imagens (<img>, <picture>) são copiadas e tem hash gerado
Mídia (<video>, <audio>, <source>) são copiadas e tem hash gerado
Qualquer tag <link> com um atributo href apontando para um arquivo local é reescrito para o novo caminho e tem hash gerado

Todos os caminhos são resolvidos relativos ao seu arquivo HTML, tornando fácil organizar seu projeto da maneira que quiser.

Como isso funciona

Este é um pequeno wrapper em torno do suporte do Bun para imports HTML em JavaScript.

Adicionando um backend ao seu frontend

Para adicionar um backend ao seu frontend, você pode usar a opção "routes" em Bun.serve.

Saiba mais na documentação full-stack.

Single Page Apps (SPA) ​

Multi-page apps (MPA) ​

Padrões glob ​

Normalização de caminho ​

JavaScript, TypeScript e JSX ​

ES Modules e CommonJS ​

CSS ​

Referenciando assets locais em CSS ​

Importando CSS em JavaScript ​

Plugins ​

Tailwind CSS ​

Variáveis de ambiente inline ​

Servidor de desenvolvimento (runtime) ​

Build para produção ​

Exemplo ​

Ecoar logs de console do navegador para o terminal ​

Editar arquivos no navegador ​

Atalhos de Teclado ​

Build para Produção ​

Watch Mode ​

API de Plugin ​

O Que é Processado? ​

Como isso funciona ​

Adicionando um backend ao seu frontend ​

Single Page Apps (SPA)

Multi-page apps (MPA)

Padrões glob

Normalização de caminho

JavaScript, TypeScript e JSX

ES Modules e CommonJS

CSS

Referenciando assets locais em CSS

Importando CSS em JavaScript

Plugins

Tailwind CSS

Variáveis de ambiente inline

Servidor de desenvolvimento (runtime)

Build para produção

Exemplo

Ecoar logs de console do navegador para o terminal

Editar arquivos no navegador

Atalhos de Teclado

Build para Produção

Watch Mode

API de Plugin

O Que é Processado?

Como isso funciona

Adicionando um backend ao seu frontend