Configuración de una Aplicación TypeScript con Bun

Si has estado gestionando proyectos TypeScript con Node.js, conoces la fricción: instalar ts-node o tsx, configurar un paso de compilación, conectar tus scripts y solo entonces comenzar a escribir código. Bun elimina la mayor parte de esa sobrecarga. Es un runtime moderno de JavaScript que ejecuta archivos TypeScript directamente, incluye un gestor de paquetes integrado y actúa como ejecutor de tareas—todo en una herramienta. Esta guía te lleva a través de una configuración completa de proyecto TypeScript con Bun para que puedas pasar de cero a ejecutar TypeScript en minutos.

¿Qué es Bun y Por Qué Usarlo para TypeScript?

Bun es un runtime rápido de JavaScript construido sobre JavaScriptCore y escrito en Zig. Lo que lo hace destacar para el desarrollo TypeScript es que transpila nativamente archivos .ts y .tsx en tiempo de ejecución—sin necesidad de un paso de compilación separado. A diferencia de la combinación Node.js + ts-node, Bun maneja la transpilación internamente, lo que significa tiempos de inicio notablemente más rápidos y un flujo de trabajo de desarrollo más simple.

Más allá del runtime, Bun reemplaza varias herramientas a la vez:

• Runtime – ejecuta TypeScript y JavaScript directamente
• Gestor de paquetes – alternativa más rápida a npm, yarn o pnpm
• Ejecutor de tareas – ejecuta scripts definidos en package.json

Creación de un Nuevo Proyecto TypeScript con Bun

Comienza instalando Bun, luego crea un nuevo proyecto:

bun init

Bun te solicitará un punto de entrada. Usa src/index.ts para mantener las cosas organizadas:

entry point (index.ts): src/index.ts

Esto genera una estructura de proyecto mínima:

my-app/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
└── bun.lock

El archivo bun.lock es el archivo de bloqueo de dependencias de Bun utilizado por el gestor de paquetes de Bun para asegurar instalaciones consistentes.

Instalación de las Definiciones de Tipo de Bun

Si @types/bun no está ya presente en tu proyecto, instálalo como dependencia de desarrollo para obtener IntelliSense adecuado y verificación de tipos para las APIs específicas de Bun:

bun add -d @types/bun

Esto te da acceso tipado a las APIs integradas de Bun como Bun.serve(), Bun.file() y bun:sqlite. Consulta la documentación oficial de TypeScript de Bun para más detalles.

tsconfig.json Recomendado para Proyectos Bun

Bun funciona sin un tsconfig.json, pero querrás uno para soporte del IDE y verificación de tipos. La configuración clave para la configuración TypeScript de Bun es "moduleResolution": "bundler", que se alinea con cómo Bun resuelve módulos internamente.

Otras opciones importantes a incluir:

• "target": "ESNext" y "lib": ["ESNext"] — usa características modernas de JavaScript
• "strict": true — detecta errores tempranamente
• "noEmit": true — Bun maneja la ejecución, así que no necesitas salida compilada
• "verbatimModuleSyntax": true — asegura importaciones limpias de solo tipos
• "allowImportingTsExtensions": true — te permite importar archivos .ts con sus extensiones

Aquí hay un ejemplo completo:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ESNext"],
    "strict": true,
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

⚠️ Importante: El transpilador de Bun elimina las anotaciones de tipo por velocidad—no realiza verificación completa de tipos en tiempo de ejecución. Ejecuta bunx tsc --noEmit por separado durante el desarrollo o en CI para detectar errores de tipo.

Ejecución de Archivos TypeScript y Gestión de Scripts

Ejecutar un archivo TypeScript con Bun es sencillo:

bun run src/index.ts

Para desarrollo con reinicios automáticos en cambios de archivos, usa el modo watch:

bun --watch src/index.ts

Agrega tus flujos de trabajo comunes a los scripts de package.json:

{
  "scripts": {
    "dev": "bun --watch src/index.ts",
    "start": "bun run src/index.ts",
    "typecheck": "bunx tsc --noEmit"
  }
}

Bun ejecuta estos scripts directamente—no se necesita ejecutor de tareas adicional.

Qué Más Cubre Bun

Una vez que tu configuración de proyecto TypeScript con Bun esté en su lugar, tienes acceso a varias capacidades integradas sin agregar dependencias:

• Ejecutor de pruebas — bun test soporta una API compatible con Jest desde el inicio
• Bundler — bun build maneja el empaquetado de assets frontend
• SQLite — bun:sqlite proporciona una interfaz de base de datos nativa y tipada

Estas no son requeridas para una configuración básica, pero están disponibles en el momento que las necesites. Puedes explorar el conjunto completo de características en la documentación oficial de Bun.

Conclusión

El cambio principal al usar TypeScript con Bun es aceptar que el runtime maneja la transpilación mientras que tsc maneja la seguridad de tipos—son preocupaciones separadas. Una vez que esto queda claro, el flujo de trabajo es limpio: inicializa un proyecto, instala @types/bun si es necesario, configura tu tsconfig.json con resolución de módulos estilo bundler, y ejecuta tus archivos TypeScript directamente. Sin pipeline de compilación que mantener, sin herramientas extra que instalar.

Preguntas Frecuentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.