Introducción

Bun es una herramienta moderna para trabajar con aplicaciones JavaScript y TypeScript. Puede actuar como runtime, gestor de paquetes, ejecutor de scripts, bundler y test runner. En la práctica, muchas tareas que con Node.js harías usando node, npm, npx, herramientas de empaquetado y librerías de pruebas, con Bun se concentran en el comando bun.

La forma más sencilla de entender Bun es verlo como una alternativa a Node.js. Para un estudiante que empieza, muchas operaciones son muy parecidas: ejecutar un archivo, instalar dependencias, lanzar scripts de package.json o arrancar un servidor de desarrollo. La diferencia es que Bun intenta hacerlo con una herramienta integrada y muy rápida.

Esto no significa que Bun sustituya siempre a Node.js. Node.js sigue siendo el estándar más extendido y tiene mayor presencia en empresas, documentación, servidores y proyectos existentes. Bun es una alternativa interesante, especialmente en proyectos nuevos o en entornos donde se valora la velocidad de instalación, ejecución y herramientas integradas.

Conocimiento previo

• JavaScript
• Node.js
• TypeScript
• Uso básico de terminal.
• Conceptos de package.json, dependencias y scripts npm.

Referencias

• Bun - Documentation
• Bun - Installation
• Bun - Runtime
• Bun - Package manager
• Bun - Bundler
• Bun - Test runner
• Bun - Node.js compatibility

Índice

1. Qué es Bun
2. Bun como alternativa a Node.js
3. Instalación y comprobación
4. Ejecutar JavaScript y TypeScript
5. Crear un proyecto con bun init
6. Gestión de paquetes con Bun
7. Scripts de package.json con bun run
8. bunx como alternativa a npx
9. Servidor HTTP básico con Bun
10. Bundler integrado
11. Pruebas con bun test
12. Variables de entorno
13. Diferencias prácticas entre Bun y Node.js
14. Cuándo conviene usar Bun y cuándo Node.js
15. Buenas prácticas iniciales
16. Ejercicios

1. Qué es Bun

Bun es un conjunto de herramientas para JavaScript y TypeScript. Su objetivo es reducir el número de piezas necesarias para desarrollar una aplicación moderna.

Puede funcionar como:

• Runtime para ejecutar JavaScript y TypeScript.
• Gestor de paquetes compatible con el ecosistema npm.
• Ejecutor de scripts definidos en package.json.
• Alternativa a npx mediante bunx.
• Bundler para preparar código para navegador o producción.
• Test runner para ejecutar pruebas.
• Servidor HTTP mediante APIs propias como Bun.serve.

TODO: añadir imagen con comparación visual entre Node.js, npm, bundler, test runner y Bun como herramienta integrada.

Bun no cambia el lenguaje JavaScript. Sigues escribiendo JavaScript o TypeScript. Lo que cambia es la herramienta que ejecuta, instala, empaqueta o prueba el proyecto.

2. Bun como alternativa a Node.js

Node.js y Bun ocupan un espacio parecido: ambos permiten ejecutar JavaScript fuera del navegador. Por eso, en muchos comandos básicos, la experiencia es muy similar.

La similitud es intencional. Bun busca ser compatible con muchos proyectos del ecosistema Node.js, especialmente aquellos que usan package.json y paquetes npm.

3. Instalación y comprobación

En Windows, Bun puede instalarse desde PowerShell:

# Terminal
powershell -c "irm bun.sh/install.ps1|iex"

En Linux, macOS o WSL, la instalación habitual se realiza con:

# Terminal
curl -fsSL https://bun.sh/install | bash

Después de instalar, comprueba la versión:

# Terminal
bun --version

Si el comando no se reconoce, revisa si necesitas reiniciar la terminal, actualizar el PATH o comprobar en qué entorno lo has instalado: Windows, PowerShell, WSL o Git Bash.

4. Ejecutar JavaScript y TypeScript

Con Bun puedes ejecutar un archivo JavaScript:

const nombre = 'Ada';
console.log(`Hola, ${nombre}`);

# Terminal
bun saludo.js

También puedes ejecutar TypeScript directamente:

const nombre: string = 'Ada';
console.log(`Hola, ${nombre}`);

# Terminal
bun saludo.ts

Esta es una diferencia práctica importante frente a Node.js: Bun entiende TypeScript de forma directa para ejecutar archivos, aunque eso no elimina la utilidad de aprender tsconfig, tipos y compilación cuando el proyecto crece.

5. Crear un proyecto con bun init

Puedes crear un proyecto básico con:

# Terminal
mkdir proyecto-bun
cd proyecto-bun
bun init

Una estructura mínima puede incluir:

proyecto-bun/
  index.ts
  package.json
  bun.lock

El archivo bun.lock cumple una función parecida a package-lock.json: registra versiones exactas de dependencias para que la instalación sea reproducible.

6. Gestión de paquetes con Bun

Bun puede instalar paquetes del ecosistema npm.

# Terminal
bun install
bun add date-fns
bun add -d typescript
bun remove date-fns

Un package.json puede seguir teniendo una estructura familiar:

{
  "name": "proyecto-bun",
  "version": "1.0.0",
  "scripts": {
    "dev": "bun index.ts",
    "test": "bun test"
  },
  "dependencies": {},
  "devDependencies": {}
}

Bun está pensado para integrarse con el ecosistema npm, pero si un paquete depende de comportamientos muy concretos de Node.js conviene comprobar compatibilidad.

7. Scripts de package.json con bun run

Igual que con npm, puedes definir scripts en package.json y ejecutarlos con Bun.

{
  "scripts": {
    "start": "bun servidor.ts",
    "dev": "vite",
    "test": "bun test"
  }
}

# Terminal
bun run start
bun run dev
bun run test

En muchos proyectos frontend, bun run dev puede ejecutar el mismo script que antes lanzabas con npm run dev, siempre que las dependencias sean compatibles.

8. bunx como alternativa a npx

bunx permite ejecutar paquetes sin instalarlos globalmente, de forma parecida a npx.

# Terminal
bunx cowsay "Hola, Bun"

Es útil para ejecutar generadores de proyectos, lanzar comandos puntuales o probar herramientas sin instalación global.

9. Servidor HTTP básico con Bun

Bun incluye APIs propias para crear servidores HTTP de forma sencilla.

const server = Bun.serve({
  port: 3000,
  routes: {
    '/': () => new Response('Hola desde Bun'),
  },
});

console.log(`Servidor disponible en ${server.url}`);

# Terminal
bun servidor.ts

Este ejemplo demuestra que Bun puede usarse también para servidor. En DWEC nos interesa principalmente como herramienta de desarrollo cliente, pero es útil ver que comparte territorio con Node.js también en backend.

10. Bundler integrado

Un bundler toma archivos de entrada y genera archivos preparados para ejecutarse en navegador o producción. Bun incluye un bundler propio.

# Terminal
bun build ./src/index.ts --outdir ./dist

No significa que debas sustituir automáticamente Vite, Angular CLI u otras herramientas. En muchos proyectos educativos seguiremos usando la herramienta recomendada por el framework.

11. Pruebas con bun test

Bun incorpora un test runner.

export function sumar(a: number, b: number): number {
  return a + b;
}

import { expect, test } from 'bun:test';
import { sumar } from './calculadora';

test('suma dos números', () => {
  expect(sumar(2, 3)).toBe(5);
});

# Terminal
bun test

Para proyectos pequeños, esto evita instalar una herramienta adicional de pruebas.

12. Variables de entorno

Bun puede leer variables de entorno mediante process.env, igual que muchos proyectos Node.js.

const port = process.env.PORT ?? '3000';
console.log(`Puerto: ${port}`);

En PowerShell:

# Terminal
$env:PORT="4000"; bun config.ts

En Linux o macOS:

# Terminal
PORT=4000 bun config.ts

Bun también puede cargar variables desde archivos .env, lo que reduce la necesidad de instalar paquetes como dotenv en muchos casos.

13. Diferencias prácticas entre Bun y Node.js

La diferencia principal para clase es esta: Bun se usa de forma muy parecida a Node.js, pero agrupa más funciones y puede simplificar comandos. Aun así, Node.js sigue siendo una base que conviene dominar.

14. Cuándo conviene usar Bun y cuándo Node.js

Bun puede ser buena opción cuando quieres probar una herramienta rápida para instalar dependencias, ejecutar scripts TypeScript directamente o trabajar en un proyecto nuevo que no depende de muchas APIs específicas de Node.js.

Node.js suele ser mejor elección cuando el proyecto ya está basado en Node.js y npm, hay dependencias nativas, el entorno de despliegue exige Node.js o necesitas máxima compatibilidad y documentación disponible.

En FP es útil conocer ambos: Node.js como estándar general y Bun como alternativa moderna que puede aparecer en proyectos actuales.

15. Buenas prácticas iniciales

• Aprende primero qué problema resuelve Node.js y después compara Bun.
• No mezcles npm install y bun install sin entender qué lockfile usa el proyecto.
• Usa una sola herramienta de instalación por proyecto salvo indicación del equipo.
• Comprueba bun --version antes de seguir tutoriales.
• Revisa compatibilidad si el proyecto usa dependencias complejas.
• No sustituyas Vite, Angular CLI o herramientas del framework sin una razón clara.
• Mantén package.json como referencia central de scripts.
• No subas secretos ni archivos .env con credenciales.

16. Ejercicios