Cómo migrar Astro a Bun en Cloudflare Pages (guía 2026)

Cambiar Node.js y npm por Bun en Cloudflare Pages puede reducir los tiempos de instalación de dependencias entre 10 y 30 veces y recortar entre un 15 y un 30 % las compilaciones con mucha E/S. Bun es un runtime de compilación compatible en Cloudflare Pages, no un experimento. Si tienes un sitio estático de Astro con Node.js y npm, esta guía cubre la migración completa. Tanto si creaste un blog gratis con Astro y Cloudflare como si migraste de WordPress a Astro, el cambio a Bun es el siguiente paso para conseguir despliegues más rápidos.

Requisitos previos y compatibilidad

Compatibilidad de versiones de Astro

Esta migración funciona igual de Astro v3 a v7 en sitios estáticos (SSG). Astro 7 añadió un compilador en Rust y Rolldown (Vite 8), lo que se traduce en compilaciones más rápidas. Puedes leer más sobre el rendimiento de compilación de Astro 7 para conocer los detalles. Los pasos de la migración a Bun en sí no han cambiado entre versiones de Astro.

Usuarios de SSR: una advertencia importante

Si usas @astrojs/cloudflare para el renderizado del lado del servidor con Astro 6+, Cloudflare Pages ya no es compatible con despliegues SSR. Desde @astrojs/cloudflare v13, solo Cloudflare Workers es compatible con el renderizado bajo demanda. Los sitios estáticos no se ven afectados por este cambio.

1. Instala Bun

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

brew install bun

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

npm install -g bun

Después de instalarlo, verifica que funciona:

bun --version

Deberías ver 1.3.x o superior. Si obtienes command not found, reinicia tu terminal o ejecuta source ~/.bashrc / source ~/.zshrc.

Puedes consultar Bun vs NPM, Yarn, PNPM y otros para una comparación detallada de Bun frente a otros gestores de paquetes.

2. Elimina los archivos de bloqueo existentes

Elimina el lockfile del gestor de paquetes que estuvieras usando antes:

# Si usabas npm:
rm package-lock.json

# Si usabas pnpm:
rm pnpm-lock.yaml

# Si usabas Yarn:
rm yarn.lock

Bun crea su propio lockfile: bun.lock (formato de texto, predeterminado desde ~v1.2) o bun.lockb (binario). Se genera en el próximo bun install.

3. Instala las dependencias con Bun

Ejecuta bun install para instalar las dependencias de tu proyecto:

bun install

Esto lee tu package.json y descarga los paquetes mucho más rápido que npm (normalmente de 10 a 30 veces en instalaciones limpias). La mayor ventaja es el tiempo de instalación de dependencias en CI/CD.

Sharp, la biblioteca de optimización de imágenes de Astro, funciona con Bun de forma nativa. Estuvo rota en 2023-2024, pero se corrigió desde Bun ~1.1.x. No hacen falta workarounds.

Si más adelante necesitas actualizar los paquetes a sus últimas versiones, mira cómo actualizar paquetes con Bun.

4. Prueba tu proyecto de Astro en local

Inicia el servidor de desarrollo para asegurarte de que todo funciona:

bun run dev

Abre http://localhost:4321 y verifica que tus páginas cargan correctamente. Después, prueba la compilación de producción:

bun run build

El directorio dist/ debería crearse sin errores.

Entendiendo el flag --bun

Hay una distinción que la mayoría de las guías omiten:

• bun run dev / bun run build ejecuta Astro a través de la capa de compatibilidad con Node.js de Bun. Es estable y está recomendado para la mayoría de los proyectos.
• bun run --bun dev / bun run --bun build ejecuta Astro usando el runtime real de Bun. Es más rápido, pero algunas integraciones pueden tener asperezas.

Si quieres exprimir más velocidad en tus compilaciones, consulta las guías sobre el rendimiento de compilación de Astro 7 y cómo optimizar la velocidad de compilación de Astro.

5. Configura Cloudflare Pages para Bun

Inicia sesión en el panel de Cloudflare y ve a la configuración de tu proyecto. Tendrás que actualizar el comando de compilación y, opcionalmente, fijar tu versión de Bun. Si aún no has configurado Cloudflare Pages, mira primero cómo desplegar un sitio de Astro en Cloudflare Pages.

Actualiza el comando de compilación

Cambia el comando de compilación de Cloudflare Pages a:

bun run build

bun run --bun build

El recomendado bun run build usa la capa de compatibilidad con Node.js de Bun, que es estable y más rápida que npm. La variante --bun usa el runtime nativo de Bun. Es más rápida, pero puede no funcionar con todas las integraciones. Empieza con la opción recomendada.

Fija tu versión de Bun con BUN_VERSION

En Cloudflare Dashboard → Settings → Environment variables, añade:

BUN_VERSION=1.3.14

Sustituye 1.3.14 por la última versión estable de Bun. Fijar la versión evita roturas inesperadas cuando Cloudflare actualiza la versión predeterminada de Bun en su imagen de compilación.

Versiones del sistema de compilación de Cloudflare Pages (v2 frente a v3)

Cloudflare Pages tiene tres versiones del sistema de compilación:

• v3: predeterminada para proyectos nuevos. Bun 1.2.15, Node 22.16.0, Ubuntu 22.04.2.
• v2: Bun 1.1.33 y Node 18.17.1 por defecto. Migrará automáticamente a v3 para febrero de 2027.
• v1: obsoleta. Migrará automáticamente a v3 para septiembre de 2026.

El plan gratuito de Cloudflare Pages te da 500 compilaciones al mes, 1 compilación simultánea y un límite estricto de 20 minutos por compilación. Las instalaciones más rápidas de Bun ayudan a que los proyectos grandes se mantengan por debajo de ese límite. No hay coste adicional por usar Bun en lugar de Node.

6. Despliega en Cloudflare

Confirma tus cambios y súbelos a tu repositorio Git:

git add .
git commit -m "Migrate to Bun"
git push

Cloudflare detectará el push y empezará a compilar con la nueva configuración de Bun. Puedes seguir el progreso en Cloudflare Dashboard → Pages → tu proyecto → Deployments.

7. Verifica el despliegue

No des por hecho que funcionó. Comprueba lo siguiente:

Cómo verificarlo:

1. Log de compilación: Cloudflare Dashboard → Pages → Deployments → haz clic en la última compilación → lee el log. Busca bun install vX.X.X cerca del principio.
2. Revisión del sitio: visita tu URL de producción y navega por varias páginas.
3. Revisión de la consola: abre las DevTools del navegador → pestaña Console. Busca errores o advertencias que no estuvieran antes.

# Comprobación HTTP rápida desde tu terminal:
curl -I https://your-site.pages.dev

Deberías obtener una respuesta 200 OK.

Resolución de problemas habituales

npm install -g --allow-scripts=bun bun && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build

BUN_VERSION=1.3.14

git add bun.lock
git commit -m "Add Bun lockfile"
git push

npm install -g --allow-scripts=bun bun && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build

Esto instala un Bun nuevo durante la compilación. Si tu compilación supera el tiempo límite, las instalaciones más rápidas de Bun pueden ayudar. El límite de 20 minutos por compilación es estricto. Mira cómo optimizar la velocidad de compilación de Astro para más consejos.

Cuándo no migrar a Bun

Conclusión

Bun en Cloudflare Pages es un runtime compatible con un sistema de compilación maduro (v3) y un fijado de versiones adecuado. La migración es un esfuerzo único: cambia tu lockfile, instala las dependencias con bun install, actualiza el comando de compilación a bun run build y fija BUN_VERSION en Cloudflare Dashboard. Obtienes instalaciones de dependencias más rápidas, compilaciones más rápidas en proyectos con mucha E/S y una experiencia de desarrollo local más sencilla.

Si empiezas un proyecto nuevo, puedes crear un blog gratis con Astro y Cloudflare con Bun desde el primer día. Si estás valorando plataformas de despliegue alternativas para sitios estáticos de Astro, Bunny.net es una opción sólida. Aquí tienes cómo desplegar Astro en Bunny.net.