Bun JS HTML y sitios estáticos

El empaquetador de Bun tiene soporte de primera clase para HTML. Construye sitios estáticos, landing pages y aplicaciones web sin configuración. Solo apunta Bun a tu archivo HTML y se encarga de todo lo demás.

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 comenzar, pasa archivos HTML a bun.

bash

bun ./index.html

Bun v1.3.3
listo en 6.62ms
→ http://localhost:3000/
Presiona h + Enter para mostrar atajos

El servidor de desarrollo de Bun proporciona características poderosas sin configuración:

Empaquetado Automático - Empaqueta y sirve tu HTML, JavaScript y CSS
Soporte Multi-Entrada - Maneja múltiples entrypoints HTML y entrypoints glob
JavaScript Moderno - Soporte para TypeScript y JSX integrado
Configuración Inteligente - Lee tsconfig.json para rutas, opciones JSX, decoradores experimentales y más
Plugins - Plugins para TailwindCSS y más
ESM y CommonJS - Usa ESM y CommonJS en tus archivos JavaScript, TypeScript y JSX
Empaquetado y Minificación CSS - Empaqueta CSS desde etiquetas <link> y declaraciones @import
Gestión de Assets - Copiado y hasheado automático de imágenes y assets; Reescribe rutas de assets en JavaScript, CSS y HTML

Single Page Apps (SPA)

Cuando pasas un único archivo .html a Bun, Bun lo usará como ruta de fallback para todas las rutas. Esto lo hace perfecto para single page apps que usan enrutamiento del lado del cliente:

bash

bun index.html

Bun v1.3.3
listo en 6.62ms
→ http://localhost:3000/
Presiona h + Enter para mostrar atajos

Tu React u otra SPA funcionará sin configuración adicional. Todas las rutas como /about, /users/123, etc. servirán el mismo archivo HTML, permitiendo que tu router del lado del cliente maneje la navegación.

html

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

Multi-page apps (MPA)

Algunos proyectos tienen varias rutas separadas o archivos HTML como entry points. Para soportar múltiples entrypoints, pásalos todos a bun:

bash

bun ./index.html ./about.html

txt

Bun v1.3.3
listo en 6.62ms
→ http://localhost:3000/
Rutas:
  / ./index.html
  /about ./about.html
Presiona h + Enter para mostrar atajos

Esto servirá:

index.html en /
about.html en /about

Patrones Glob

Para especificar múltiples archivos, puedes usar patrones glob que terminan en .html:

bash

bun ./**/*.html

Bun v1.3.3
listo en 6.62ms
→ http://localhost:3000/
Rutas:
  / ./index.html
  /about ./about.html
Presiona h + Enter para mostrar atajos

Normalización de Rutas

La ruta base se elige del prefijo común más largo entre todos los archivos.

bash

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

Bun v1.3.3
listo en 6.62ms
→ http://localhost:3000/
Rutas:
  / ./index.html
  /about ./about/index.html
  /about/foo ./about/foo/index.html
Presiona h + Enter para mostrar atajos

JavaScript, TypeScript y JSX

El transpilador de Bun implementa nativamente soporte para JavaScript, TypeScript y JSX. Aprende más sobre loaders en Bun.

NOTE

El transpilador de Bun también se usa en runtime.

ES Modules y CommonJS

Puedes usar ESM y CJS en tus archivos JavaScript, TypeScript y JSX. Bun manejará la transpilación y el empaquetado automáticamente.

No hay pre-construcción o paso de optimización separado. Todo se hace al mismo tiempo.

Aprende más sobre resolución de módulos en Bun.

CSS

El parser CSS de Bun también está implementado nativamente (alrededor de 58,000 líneas de Zig).

También es un empaquetador CSS. Puedes usar @import en tus archivos CSS para importar otros archivos CSS.

Por ejemplo:

css

@import "./abc.css";

.container {
  background-color: blue;
}

css

body {
  background-color: red;
}

Esto genera:

css

body {
  background-color: red;
}

.container {
  background-color: blue;
}

Referenciar assets locales en CSS

Puedes referenciar assets locales en tus archivos CSS.

css

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

Esto copiará ./logo.png al directorio de salida y reescribirá la ruta en el archivo CSS para incluir un hash de contenido.

css

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

Importar CSS en JavaScript

Para asociar un archivo CSS con un archivo JavaScript, puedes importarlo en tu archivo JavaScript.

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

Esto genera ./app.css y ./app.js en el directorio de salida. Todos los archivos CSS importados desde JavaScript se empaquetarán en un único archivo CSS por entrypoint. Si importas el mismo archivo CSS desde múltiples archivos JavaScript, solo se incluirá una vez en el archivo CSS de salida.

Plugins

El servidor de desarrollo soporta plugins.

Tailwind CSS

Para usar TailwindCSS, instala el plugin bun-plugin-tailwind:

bash

# O cualquier cliente npm
bun install --dev bun-plugin-tailwind

Luego, agrega el plugin a tu bunfig.toml:

bunfig.toml

toml

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

Luego, referencia TailwindCSS en tu HTML vía etiqueta <link>, @import en CSS, o import en JavaScript.

html

<!-- Referencia TailwindCSS en tu HTML -->
<link rel="stylesheet" href="tailwindcss" />

styles.css

css

@import "tailwindcss";

import "tailwindcss";

Variables de entorno en línea

Bun puede reemplazar referencias process.env.* en tu JavaScript y TypeScript con sus valores reales en tiempo de construcción. Esto es útil para inyectar configuración como URLs de API o feature flags en tu código frontend.

Servidor de desarrollo (runtime)

Para incluir variables de entorno en línea al usar bun ./index.html, configura la opción env en tu bunfig.toml:

bunfig.toml

toml

[serve.static]
env = "PUBLIC_*"  # solo variables de entorno que comienzan con PUBLIC_ (recomendado)
# env = "inline"  # incluir todas las variables de entorno
# env = "disable" # deshabilitar reemplazo de variables de entorno (predeterminado)

NOTE

Esto solo funciona con referencias literales `process.env.FOO`, no `import.meta.env` o acceso indirecto como `const env = process.env; env.FOO`.

Si una variable de entorno no está establecida, podrías ver errores en runtime como ReferenceError: process is not defined en el navegador.

Luego ejecuta el servidor de desarrollo:

bash

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

Construir para producción

Al construir HTML estático para producción, usa la opción env para incluir variables de entorno en línea:

bash

# Incluir todas las variables de entorno
bun build ./index.html --outdir=dist --env=inline

# Solo variables de entorno con un prefijo específico (recomendado)
bun build ./index.html --outdir=dist --env=PUBLIC_*

// Incluir todas las variables de entorno
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "inline", 
});

// Solo variables de entorno con un prefijo específico (recomendado)
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "PUBLIC_*", 
});

Ejemplo

Dado este archivo fuente:

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

Y ejecutando con PUBLIC_API_URL=https://api.example.com:

bash

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

La salida empaquetada contendrá:

dist/app.js

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

Repetir logs de consola del navegador a la terminal

El servidor de desarrollo de Bun soporta transmitir logs de consola del navegador a la terminal.

Para habilitar, pasa la flag --console del CLI.

bash

bun ./index.html --console

Bun v1.3.3
listo en 6.62ms
→ http://localhost:3000/
Presiona h + Enter para mostrar atajos

Cada llamada a console.log o console.error se transmitirá a la terminal que inició el servidor. Esto es útil para ver errores del navegador en el mismo lugar donde ejecutas tu servidor. Esto también es útil para agentes de IA que observan la salida de la terminal.

Internamente, esto reutiliza la conexión WebSocket existente de la recarga de módulos en caliente para enviar los logs.

Editar archivos en el navegador

El servidor de desarrollo frontend de Bun tiene soporte para Carpetas de Espacio de Trabajo Automáticas en Chrome DevTools, lo que te permite guardar ediciones a archivos en el navegador.

Atajos de Teclado

Mientras el servidor está ejecutándose:

o + Enter - Abrir en el navegador
c + Enter - Limpiar consola
q + Enter (o Ctrl+C) - Salir del servidor

Construir para Producción

Cuando estés listo para desplegar, usa bun build para crear bundles de producción optimizados:

bash

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

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

Modo Watch

Puedes ejecutar bun build --watch para observar cambios y reconstruir automáticamente. Esto funciona bien para desarrollo de librerías.

API de Plugins

¿Necesitas más control? Configura el empaquetador a través de la API de JavaScript y usa HTMLRewriter integrado de Bun para preprocesar HTML.

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

  plugins: [
    {
      // Un plugin que hace cada etiqueta HTML minúscula
      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 {
            // El empaquetador de Bun escaneará el HTML en busca de etiquetas <script>, <link rel="stylesheet"> y otros assets
            // y los empaquetará automáticamente
            contents: rewriter.transform(html),
            loader: "html",
          };
        });
      },
    },
  ],
});

¿Qué se Procesa?

Bun maneja automáticamente todos los assets web comunes:

Scripts (<script src>) se ejecutan a través del empaquetador JavaScript/TypeScript/JSX de Bun
Hojas de estilo (<link rel="stylesheet">) se ejecutan a través del parser y empaquetador CSS de Bun
Imágenes (<img>, <picture>) se copian y hashean
Media (<video>, <audio>, <source>) se copian y hashean
Cualquier etiqueta <link> con un atributo href apuntando a un archivo local se reescribe a la nueva ruta, y se hashea

Todas las rutas se resuelven relativas a tu archivo HTML, haciendo fácil organizar tu proyecto como quieras.

Cómo funciona esto

Esto es un pequeño wrapper alrededor del soporte de Bun para imports HTML en JavaScript.

Agregar un backend a tu frontend

Para agregar un backend a tu frontend, puedes usar la opción "routes" en Bun.serve.

Aprende más en la documentación full-stack.

Single Page Apps (SPA) ​

Multi-page apps (MPA) ​

Patrones Glob ​

Normalización de Rutas ​

JavaScript, TypeScript y JSX ​

ES Modules y CommonJS ​

CSS ​

Referenciar assets locales en CSS ​

Importar CSS en JavaScript ​

Plugins ​

Tailwind CSS ​

Variables de entorno en línea ​

Servidor de desarrollo (runtime) ​

Construir para producción ​

Ejemplo ​

Repetir logs de consola del navegador a la terminal ​

Editar archivos en el navegador ​

Atajos de Teclado ​

Construir para Producción ​

Modo Watch ​

API de Plugins ​

¿Qué se Procesa? ​

Cómo funciona esto ​

Agregar un backend a tu frontend ​

Single Page Apps (SPA)

Multi-page apps (MPA)

Patrones Glob

Normalización de Rutas

JavaScript, TypeScript y JSX

ES Modules y CommonJS

CSS

Referenciar assets locales en CSS

Importar CSS en JavaScript

Plugins

Tailwind CSS

Variables de entorno en línea

Servidor de desarrollo (runtime)

Construir para producción

Ejemplo

Repetir logs de consola del navegador a la terminal

Editar archivos en el navegador

Atajos de Teclado

Construir para Producción

Modo Watch

API de Plugins

¿Qué se Procesa?

Cómo funciona esto

Agregar un backend a tu frontend