La solución definitiva: Migrando Next.js 15 de Cloudflare Pages a Workers con OpenNext
Si has estado construyendo aplicaciones en Next.js 15 y desplegándolas en Cloudflare Pages utilizando @cloudflare/next-on-pages, es probable que te hayas topado con un muro.
El temido error "Invalid prerender config", la renderización inconsistente entre rutas estáticas y dinámicas, y los choques de configuración en el runtime edge han sido grandes dolores de cabeza para la comunidad. Después de horas depurando estos exactos problemas en el sitio de mi portfolio, finalmente encontré la solución a prueba de balas: Migrar de Cloudflare Pages a Cloudflare Workers utilizando OpenNext.
En esta guía, te mostraré exactamente por qué Next.js en Pages falla y cómo migrar limpiamente tu arquitectura a Cloudflare Workers para un despliegue impecable y robusto.
El Problema: Limitaciones de Next-on-Pages
Cloudflare Pages fue diseñado originalmente para sitios puramente estáticos. Aunque ha evolucionado para soportar renderizado del lado del servidor (SSR) y Edge Functions a través de @cloudflare/next-on-pages, la integración con el App Router de Next.js 15 sigue siendo frágil.
Cuando mezclas rutas estáticas SSG (como publicaciones de blog) con rutas edge dinámicas (como endpoints de API o consultas a bases de datos), el proceso de construcción a menudo se bloquea:
Error: Invalid prerender config for /app/[locale]/about
The following routes were not configured to run with the Edge Runtime...
El problema subyacente es una desalineación entre cómo la salida de construcción de Vercel espera que estén estructuradas las funciones y cómo next-on-pages las interpreta para el entorno de Pages.
La Solución: OpenNext y Cloudflare Workers
En lugar de pelear con el sistema de construcción de Pages, el enfoque moderno es usar OpenNext (@opennextjs/cloudflare) y desplegar directamente en Cloudflare Workers.
Workers proporcionan un verdadero entorno de ejecución serverless que se alinea perfectamente con los requisitos de SSR y rutas API de Next.js, mientras que Cloudflare Assets maneja los archivos estáticos.
Esta es la ruta de migración paso a paso.
Paso 1: Instalar Dependencias
Elimina next-on-pages e instala OpenNext para Cloudflare:
npm uninstall @cloudflare/next-on-pages
npm install -D @opennextjs/cloudflare
Paso 2: Configurar OpenNext
Crea un archivo open-next.config.ts en la raíz de tu proyecto. Esto le dice a OpenNext cómo adaptar tu construcción de Next.js para Cloudflare:
import type { OpenNextConfig } from 'open-next/types/open-next.js';
export default {
default: {
override: {
wrapper: 'cloudflare-node',
converter: 'edge',
incrementalCache: 'dummy',
tagCache: 'dummy',
queue: 'dummy',
},
},
middleware: {
external: true,
override: {
wrapper: 'cloudflare-edge',
converter: 'edge',
proxyExternalRequest: 'fetch',
},
},
} as OpenNextConfig;
Paso 3: Configurar Wrangler para Workers
Necesitas un wrangler.jsonc (o wrangler.toml) para definir el despliegue de tu Worker. Observa cómo apuntamos la entrada principal al worker generado por OpenNext y vinculamos los activos estáticos.
{
"main": ".open-next/worker.js",
"name": "your-project-name",
"compatibility_date": "2026-06-15",
"compatibility_flags": [
"nodejs_compat"
],
"assets": {
"directory": ".open-next/assets",
"binding": "ASSETS"
}
}
Paso 4: Actualizar Scripts de Construcción
Actualiza tu package.json para compilar primero con Next.js y luego procesar con OpenNext:
"scripts": {
"build": "next build && opennextjs-cloudflare",
"preview": "npm run build && wrangler dev",
"deploy": "npm run build && wrangler deploy"
}
Paso 5: Limpiar Configuraciones Edge
Con OpenNext, ya no necesitas forzar estrictamente export const runtime = 'edge' en la parte superior de cada archivo dinámico solo para apaciguar al sistema de construcción. El envoltorio cloudflare-node de OpenNext maneja de manera inteligente las APIs de Node.js y las APIs de Edge, simplificando drásticamente tu base de código.
¿Qué pasa con Cloudflare R2?
Durante esta migración, es posible que te preguntes si necesitas aprovisionar un bucket de Cloudflare R2.
La respuesta corta: No, no de inmediato.
Tus activos estáticos de Next.js (imágenes, CSS, fragmentos JS) son servidos perfectamente por el enlace de Cloudflare Assets definido en tu wrangler.jsonc.
Sin embargo, si tu aplicación escala para manejar medios subidos por usuarios, videos grandes o conjuntos de datos masivos, R2 se integra perfectamente en esta arquitectura de Worker. Simplemente vinculas el bucket R2 en tu wrangler.jsonc y accedes a él a través de env.MY_BUCKET en tus Server Actions o rutas API.
El Resultado
Al migrar a Cloudflare Workers con OpenNext, logras:
- Cero errores de compilación: No más frustraciones con configs de prerenderizado.
- Localización impecable: El enrutamiento internacionalizado (
/[locale]/) funciona sin configuración adicional. - Compatibilidad con Node.js: La bandera
nodejs_compatpermite un soporte más amplio de paquetes npm.
Cloudflare Pages es fantástico para sitios estáticos simples, pero para aplicaciones Next.js 15 ambiciosas, OpenNext en Cloudflare Workers es el camino definitivo a seguir.