Saltar al contenido principal

Bun — Package manager para JavaScript / TypeScript

⚠️ Verificar versiones antes de usar — la versión de Bun documentada aquí puede estar desactualizada. Consultar mise ls-remote bun | tail -5 o bun.sh para la versión estable más reciente. Ver politicas-core.

Qué es​

Bun es un toolkit de JavaScript/TypeScript todo-en-uno escrito en Zig. Técnicamente es capaz de reemplazar varias herramientas:

CapacidadHerramienta equivalenteUso en Wiedii
Gestor de paquetesnpm / yarn / pnpm✅ Sí — es el PM estándar
Test runnervitest / jest✅ Sí — para CLI tools sin DB/web
Script runnerts-node / tsx✅ Sí — scripts de desarrollo
Bundleresbuild / vite✅ Sí — cuando se usa
Runtime de ejecuciónnode⚠️ Depende del proyecto — ver nota abajo

Runtime en Wiedii: Bun puede ejecutar JS/TS directamente y es compatible con la mayoría de APIs de Node. Sin embargo, algunas librerías con bindings nativos (como sharp para imágenes) requieren el runtime de Node.js. Por eso Node.js es el runtime de ejecución por defecto en producción y en Docker en los proyectos de Wiedii, mientras que Bun se usa como package manager y para scripts de desarrollo. En proyectos donde todas las dependencias son compatibles con Bun, puede usarse como runtime también — evaluarlo caso a caso.

Por qué lo usamos en Wiedii​

La razón principal es velocidad como package manager: bun install es hasta 25× más rápido que npm install, y ejecuta TypeScript de forma nativa sin ts-node ni tsx para scripts de desarrollo y tests. Esto reduce la superficie de configuración de cada proyecto.

La distinción clave: Bun gestiona paquetes y corre scripts en desarrollo. Node.js ejecuta en producción cuando la compatibilidad de librerías lo requiere.

Instalación​

Bun se gestiona con mise, no directamente con brew. Esto garantiza que cada proyecto use la versión declarada en su mise.toml.

Global (disponible en cualquier directorio)​

# ~/.config/mise/config.toml
[tools]
bun = "1.3.14"
cd ~/.config/mise && mise install --yes && cd -

Por proyecto (mise.toml en la raíz del repo)​

[tools]
bun = "1.3.14"   # versión específica del proyecto
mise install --yes   # instala la versión declarada

brew install bun también funciona, pero no es el método estándar en Wiedii porque no permite versiones por proyecto. Usar siempre mise.

Comandos habituales en Wiedii​

# Instalar dependencias
bun install

# Ejecutar scripts del package.json
bun run dev
bun run build
bun run lint

# Atajo sin "run" para scripts definidos en package.json
bun dev
bun build

# Tests
bun test
bun test --watch
bun test src/utils/         # tests en un directorio concreto
bun test --coverage

# Ejecutar un archivo TypeScript directamente
bun run script.ts
bun run src/seed.ts

# Agregar dependencias
bun add <paquete>
bun add -d <paquete>        # devDependency

Los commits no se hacen con Bun: se usan con wietoo commit (binario nativo instalado por mise, sin Node) — ver wietoo-cli.

Setup estándar de un repo Wiedii​

Con wietoo (commits nativos, sin Node), el package.json de un repo ya no necesita un script commit — antes se usaba "commit": "bun --bun czg"; hoy los commits se hacen con wietoo commit, un binario instalado por mise (ver wietoo-cli).

  • lefthook install no va en package.json — lo gestiona mise.toml via [hooks].postinstall, con detección automática de CI

En mise.toml, la task de setup orquesta todo con un solo comando:

[hooks]
# experimental en mise — no requiere mise activate
# Se salta automáticamente en CI ($CI=true)
postinstall = "[ -z \"$CI\" ] && lefthook install || true"

[tasks.setup]
# ⚠️ Una sola cadena con && (NO array): el hook `toml` con reorder_arrays=true reordenaría
# los pasos al commitear y rompería el orden de ejecución.
# Encuentra package.json en root o src/ — funciona independientemente de la estructura del proyecto.
run = "mise install --yes && mise lock && pkg=$(find . -maxdepth 2 -name 'package.json' ! -path '*/node_modules/*' | head -1) && { [ -n \"$pkg\" ] && bun install --cwd \"$(dirname \"$pkg\")\" || true; }"
description = "Configura el entorno completo del proyecto"
mise run setup   # todo listo en un comando — funciona para cualquier stack

El flujo: mise install → [hooks].postinstall → lefthook install (solo en local, no en CI). bun install se ejecuta si hay package.json en root o en src/.

Bun como runtime vs Node.js como runtime​

Bun es compatible con la mayoría de APIs de Node.js (fs, path, crypto, http, etc.) y puede ejecutar código directamente. Sin embargo, en Wiedii Node.js es el runtime de ejecución por defecto porque algunas librerías con bindings nativos (sharp, canvas, libvips, etc.) requieren el runtime de Node para funcionar correctamente.

La regla práctica:

  • ¿El proyecto usa librerías con bindings nativos o dependencias que requieren Node.js? → Node.js como runtime
  • ¿El proyecto es una CLI pura o un servicio sin dependencias problemáticas? → Bun como runtime es válido, evaluar caso a caso con el TL

En ambos casos, Bun siempre es el package manager (bun install, bun add, etc.).

Si un proyecto necesita Node además de Bun, mise puede activar ambos:

# mise.toml — cuando el proyecto necesita Node además de Bun
[tools]
bun  = "1.3.14"
node = "22.14.0"

Troubleshooting rápido​

bun: command not found fuera de un proyecto:

mise ls --current   # verificar que bun está activo
cd ~/.config/mise && mise install --yes && cd -

bun install falla con permisos en node_modules:

rm -rf node_modules bun.lockb
bun install

Los tests no encuentran variables de entorno:

# Bun carga automáticamente .env — verificar que el archivo existe
ls -la .env
# o pasar el archivo explícitamente:
bun test --env-file .env.test

Los hooks no se instalan tras bun install:

# lefthook install lo gestiona mise, no bun
# Verificar que el [hooks].postinstall está en mise.toml y ejecutar:
mise install --yes

Referencias​