Saltar al contenido principal

Bun — Runtime y gestor de paquetes JS/TS

Qué es​

Bun es un runtime de JavaScript/TypeScript todo-en-uno escrito en Zig. Reemplaza en un solo binario:

ReemplazaRazón
nodeRuntime JS/TS — Bun es compatible con la mayoría de APIs de Node
npm / yarn / pnpmGestor de paquetes — instala desde el mismo package.json
vitest / jestTest runner — bun test sin configuración extra
esbuild / vite buildBundler nativo — transpila TS sin pasos extra
ts-node / tsxEjecución directa de TypeScript — bun run script.ts funciona sin compilar

Por qué lo usamos en Wiedii​

La razón principal es velocidad y simplicidad: bun install es hasta 25× más rápido que npm install, y eliminar herramientas separadas (runtime, bundler, test runner) reduce la superficie de configuración de cada proyecto.

Además, Bun ejecuta TypeScript de forma nativa — no hace falta ts-node, tsx ni pasos de compilación para scripts de desarrollo o tests.

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.2.5"   # 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

# Commit interactivo (czg — ver [czg](./czg.md))
bun commit

Setup estándar de un repo Wiedii​

El package.json de cualquier repo Wiedii incluye estos scripts mínimos:

{
  "scripts": {
    "commit": "czg"
  }
}
  • bun commit → abre el wizard de commits czg
  • 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]
run = [
  "mise trust",
  "mise install --yes",
  # Encuentra package.json en root o src/ — funciona independientemente de la estructura del proyecto
  "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/.

Compatibilidad con Node​

Bun es compatible con la mayoría de APIs de Node (fs, path, crypto, http, etc.) y con el ecosistema npm. Si un paquete o script requiere Node específicamente, mise puede activar ambos en el mismo proyecto:

# mise.toml — cuando el proyecto necesita Node además de Bun
[tools]
bun  = "1.2.5"
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​