Deploy Next.js en Cloudflare Pages desde cero

Introducción

Cloudflare Pages se ha consolidado como una de las plataformas de despliegue más potentes y económicas del mercado. Su red global de más de 300 puntos de presencia, combinada con una generosa capa gratuita y tiempos de despliegue ultrarrápidos, la convierte en una opción ideal para proyectos Next.js de cualquier escala. En este tutorial aprenderás a desplegar tu aplicación desde cero, incluyendo variables de entorno, rutas dinámicas y dominio personalizado.

Paso 1: Preparar tu proyecto Next.js

Antes de iniciar el despliegue, asegúrate de que tu proyecto está configurado correctamente. Next.js requiere el adaptador de Cloudflare para funcionar en el entorno Edge. Instala las dependencias necesarias:

npx create-next-app@latest mi-proyecto --typescript --tailwind --app
cd mi-proyecto
npm install @cloudflare/next-on-pages

El paquete `@cloudflare/next-on-pages` es el adaptador oficial que transforma tu build de Next.js en módulos Workers compatibles con el runtime de Cloudflare.

Paso 2: Configurar next.config.js

Modifica tu archivo de configuración para habilitar la compatibilidad con el Edge Runtime:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    runtime: 'edge',
  },
}
module.exports = nextConfig

Además, añade la directiva de runtime en cada route que necesite ejecutarse en el edge. Para las rutas de la App Router, incluye al inicio del archivo de ruta:

export const runtime = 'edge'

Paso 3: Configurar wrangler.toml

Crea un archivo `wrangler.toml` en la raíz del proyecto. Este archivo define la configuración de Cloudflare Pages:

name = "mi-proyecto-next"
compatibility_date = "2026-01-01"
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = ".vercel/output/static"

La flag `nodejs_compat` es esencial para que módulos de Node.js como `crypto` o `buffer` funcionen correctamente en el runtime de Cloudflare.

Paso 4: Ajustar los scripts de package.json

Actualiza los scripts de construcción para integrar el proceso de build de Cloudflare Pages:

{
  "scripts": {
    "dev": "next dev",
    "build": "npx @cloudflare/next-on-pages",
    "preview": "npm run build && wrangler pages dev",
    "deploy": "npm run build && wrangler pages deploy"
  }
}

El comando `preview` te permite probar el comportamiento exacto de producción en local antes de desplegar, lo que reduce errores inesperados en el entorno de Cloudflare.

Paso 5: Conectar el repositorio en el panel de Cloudflare

Accede al panel de Cloudflare, navega a Pages y haz clic en Create a project. Selecciona Connect to Git y autoriza el acceso a tu repositorio de GitHub o GitLab. En la configuración del proyecto, establece los siguientes parámetros de build:

• Framework preset: Next.js
• Build command: `npx @cloudflare/next-on-pages`
• Build output directory: `.vercel/output/static`
• Node.js version: 20.x

Paso 6: Configurar variables de entorno

En el panel de Cloudflare Pages, accede a Settings > Environment variables. Puedes definir variables para los entornos de producción y preview de forma independiente. Para bases de datos, APIs externas o claves privadas, usa siempre la opción de Encrypt:

DATABASE_URL=postgresql://usuario:password@host:5432/bd
NEXT_PUBLIC_API_URL=https://api.midominio.com
SECRET_KEY=valor-encriptado

Las variables con prefijo `NEXT_PUBLIC_` estarán disponibles en el cliente; el resto solo en el servidor. Nunca incluyas secretos en variables públicas.

Paso 7: Verificar el primer despliegue

Tras guardar la configuración, Cloudflare Pages iniciará automáticamente el primer build. Puedes seguir el progreso en tiempo real desde la pestaña de Deployments. Un despliegue exitoso suele tomar entre 2 y 4 minutos.

Si el build falla, revisa los logs detallados. Los errores más comunes son incompatibilidad de APIs de Node.js no soportadas en el runtime Edge, imports dinámicos sin la directiva `runtime = 'edge'`, o tamaño del bundle superior a 1MB por ruta (límite del plan gratuito). Para resolver el límite de tamaño, usa `next/dynamic` con `{ ssr: false }` para cargar componentes pesados únicamente en el cliente.

Paso 8: Configurar dominio personalizado

Una vez que el despliegue funciona correctamente en el subdominio `.pages.dev`, conecta tu dominio propio. En Settings > Custom domains, haz clic en Set up a custom domain.

Si tu dominio ya está en Cloudflare, el proceso es completamente automático. Si está en otro registrador, añade un registro CNAME:

Tipo: CNAME
Nombre: www
Valor: tu-proyecto.pages.dev
Proxy: Activado

Con el proxy de Cloudflare activado, tu sitio se beneficia automáticamente de protección DDoS, caché global, compresión Brotli y HTTP/3. Cada push a tu rama principal desencadenará un nuevo despliegue automático, mientras que los pull requests generarán entornos de preview independientes para revisión de código antes de llegar a producción.