Guía completa de Cloudflare Pages: despliega React/Vue/Next.js (configuración y errores frecuentes)

Introducción

Terminas tu proyecto React y quieres publicarlo online. Abres la página de configuración de Cloudflare Pages y te quedas mirando «Build Command» y «Build Output Directory». ¿Qué pones en Build Command? ¿npm run build o npm build? ¿El directorio de salida es build o dist? ¿Cómo configuras las variables de entorno?

Este artículo te guía paso a paso para desplegar proyectos React, Vue y Next.js en Cloudflare Pages: checklist completa de configuración, variables de entorno y solución a 5 errores frecuentes (especialmente el error nodejs_compat de Next.js).

¿Por qué elegí Cloudflare Pages?

Seguro te preguntas: si ya existen Vercel y Netlify, ¿para qué Cloudflare Pages?

Yo también empecé con Vercel. No es malo, pero el plan gratuito tiene límites. Con varios proyectos pequeños, el tráfico mensual superó los 100 GB y Vercel empezó a limitar la velocidad.

Comparé las tres plataformas y el plan gratuito de Cloudflare Pages destaca mucho:

El tráfico ilimitado es muy atractivo. Tengo varios proyectos personales en CF Pages y no me preocupo por el tráfico.

Casos ideales para Cloudflare Pages:

• Blog personal, portfolio
• Proyectos frontend medianos (SPA, sitios estáticos)
• Proyectos que necesitan aceleración global
• Proyectos con tráfico impredecible (tráfico ilimitado gratis)

Menos adecuado:

• Apps Next.js grandes con SSR complejo (el soporte de CF Pages para Next.js no es tan maduro como Vercel)
• Proyectos que requieren builds muy frecuentes (límite de 500 builds/mes)
• Proyectos que dependen de funciones exclusivas de Vercel (como Edge Middleware)

Preparación antes del despliegue

Antes de empezar, necesitas:

1. Registrar una cuenta en Cloudflare
   • Ve a Cloudflare y regístrate (gratis)
   • Verifica el correo y ya puedes empezar
2. Preparar tu repositorio de código
   • Sube el código a GitHub o GitLab
   • CF Pages obtiene el código directamente de tu repositorio Git para construir
3. Conocer la configuración de build de tu proyecto
   • ¿Usas Create React App o Vite?
   • ¿Cuál es el comando de build? (normalmente npm run build)
   • ¿En qué directorio quedan los artefactos? (CRA: build, Vite: dist)

Listo. Pasemos al despliegue en la práctica.

Flujo completo de despliegue de aplicaciones React

React es uno de los frameworks frontend más usados. He desplegado varios proyectos React en CF Pages y aquí tienes una checklist fiable.

Crear un proyecto React rápidamente (si aún no tienes uno)

Si quieres seguir el tutorial pero no tienes proyecto, puedes crear uno al vuelo:

# Método 1: Vite (recomendado, build más rápido)
npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
# Método 2: Create React App (clásico)
npx create-react-app my-react-app
cd my-react-app

Personalmente recomiendo Vite: el build es mucho más rápido. Con CRA, en proyectos grandes el build se vuelve lento.

Checklist de configuración en Cloudflare Pages

Inicia sesión en Cloudflare Dashboard, entra en Pages, haz clic en «Crear proyecto» → «Conectar a Git» y elige tu repositorio de GitHub.

Verás la página de configuración; aquí está lo clave:

Explicación de los campos:

Notas:

• En Vite, Framework preset «None» basta; CF Pages lo detecta automáticamente
• En CRA, el preset «Create React App» rellena la configuración
• Lo que más se confunde es el directorio de salida: Vite usa dist, CRA usa build; no los inviertas

Configuración de variables de entorno

Las variables de entorno en React tienen un requisito especial: deben llevar un prefijo concreto para exponerse al cliente.

Proyecto Vite:

• Prefijo obligatorio: VITE_
• Ejemplos: VITE_API_URL, VITE_API_KEY

Proyecto CRA:

• Prefijo obligatorio: REACT_APP_
• Ejemplos: REACT_APP_API_URL, REACT_APP_API_KEY

Cómo configurarlas:

1. En Cloudflare Pages (recomendado):
   • Proyecto → Settings → Environment variables
   • Haz clic en «Add variable»
   • Elige el entorno: Production o Preview
   • Introduce nombre y valor
2. Uso en el código:

// Proyecto Vite
const apiUrl = import.meta.env.VITE_API_URL;
// Proyecto CRA
const apiUrl = process.env.REACT_APP_API_URL;

Variables de entorno en desarrollo local:

Crea un archivo .env.local en la raíz del proyecto:

# Proyecto Vite
VITE_API_URL=https://api.example.com
VITE_API_KEY=your-api-key-here
# Proyecto CRA
REACT_APP_API_URL=https://api.example.com
REACT_APP_API_KEY=your-api-key-here

Recordatorio importante:

• ¡No subas .env.local a Git! Añade .env*.local en .gitignore
• Tras modificar variables de entorno, debes volver a desplegar

Resolver el 404 de rutas SPA

Si tu proyecto React usa React Router, tras el despliegue puedes encontrarte con un problema: al refrescar la página aparece 404.

En una SPA todas las rutas deben servir index.html, pero el servidor busca un archivo concreto por defecto.

Solución:

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Crea un archivo _redirects en el directorio public:

/* /index.html 200

Una sola línea: le dice al servidor que todas las rutas redirijan a index.html con código 200.

Guarda y vuelve a desplegar; las rutas funcionarán.

Verificar que el despliegue fue exitoso

Tras «Save and Deploy», CF Pages inicia el build. Puedes ver el log en «Deployments».

Señales de éxito:

• El log muestra «Success: Deployed to…»
• Te da un enlace xxx.pages.dev
• Al abrirlo ves tu proyecto

Si el build falla:

• Revisa el log para ver el error
• Causas frecuentes:
  • Directorio de salida incorrecto (Vite escrito como build, o CRA como dist)
  • Versión de Node demasiado antigua (configura la variable NODE_VERSION=18)
  • Fallo al instalar dependencias (revisa package.json)

Flujo completo de despliegue de aplicaciones Vue

El despliegue de Vue es similar al de React, pero con algunos detalles a tener en cuenta.

Crear un proyecto Vue rápidamente (opcional)

# Método 1: Vite (recomendado)
npm create vite@latest my-vue-app -- --template vue
cd my-vue-app
npm install
# Método 2: Vue CLI
vue create my-vue-app
cd my-vue-app

También recomiendo Vite por el rendimiento.

Checklist de configuración en Cloudflare Pages

Recuerda:

• Vue CLI y Vite usan dist como directorio de salida (a diferencia de React)
• Los prefijos difieren: Vite usa VITE_, Vue CLI usa VUE_APP_

Configuración de variables de entorno

Proyecto Vite + Vue:

# .env.local
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=My Vue App

Proyecto Vue CLI:

# .env.production
VUE_APP_API_BASE_URL=https://api.example.com
VUE_APP_TITLE=My Vue App

Uso en el código:

// Proyecto Vite
const apiUrl = import.meta.env.VITE_API_BASE_URL;
// Proyecto Vue CLI
const apiUrl = process.env.VUE_APP_API_BASE_URL;

Configuración de rutas con Vue Router

Si usas Vue Router, especialmente en modo History, configura la redirección; si no, al refrescar verás 404.

Método 1: archivo _redirects (recomendado)

Crea _redirects en public:

/* /index.html 200

Método 2: configurar en vite.config.js (proyectos Vite)

Si el proyecto no se despliega en la raíz, configura base:

// vite.config.js
export default {
  base: '/', // asegúrate de que sea la ruta raíz
}

Solución de problemas frecuentes

Problema 1: recursos estáticos en 404

Revisa publicPath o base en vue.config.js (Vue CLI) o vite.config.js (Vite):

// vue.config.js (Vue CLI)
module.exports = {
  publicPath: '/', // asegúrate de que sea la ruta raíz
}

Problema 2: error de build Vite «Unknown file extension»

Suele deberse a una versión de Node demasiado antigua. Añade en las variables de entorno de CF Pages:

NODE_VERSION=18

Luego vuelve a desplegar.

Flujo completo de despliegue de Next.js (¡importante!)

Desplegar Next.js en Cloudflare Pages es, sinceramente, lo más complejo de los tres frameworks. La primera vez me bloqueó medio día el error nodejs_compat; tuve que buscar mucha documentación para resolverlo.

Si tu proyecto Next.js necesita mucho SSR, sigo recomendando Vercel. Pero para sitios estáticos o SSR sencillo, CF Pages basta sobrado, y el tráfico ilimitado gratis es una ventaja enorme.

Particularidades del despliegue de Next.js

Antes de empezar, ten en cuenta estos puntos:

1. Cloudflare Pages no está pensado solo para Next.js (a diferencia de Vercel) y requiere configuración extra
2. Hay dos formas de despliegue: exportación estática (la más simple) y modo SSR (requiere adaptador)
3. Para SSR usa el adaptador @opennextjs/cloudflare (el antiguo @cloudflare/next-on-pages está obsoleto)

Método 1: exportación estática (la más simple, recomendada para empezar)

Si tu proyecto Next.js no necesita SSR, API Routes, ISR, etc., la exportación estática es la forma más sencilla.

Casos de uso:

• Blog personal
• Sitio de documentación
• Sitio de presentación
• Proyectos sin datos dinámicos en servidor

Pasos de configuración:

1. Modifica next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // clave: activa exportación estática
  images: {
    unoptimized: true, // CF Pages no soporta Image Optimization de Next.js
  },
}
module.exports = nextConfig

2. Configuración en Cloudflare Pages:

3. Despliegue:

Guarda la configuración y despliega. Tras un build exitoso tendrás un sitio estático.

Limitaciones:

• ❌ No soporta API Routes
• ❌ No soporta ISR (Incremental Static Regeneration)
• ❌ No soporta Server Components
• ❌ No soporta SSR en rutas dinámicas

Si puedes vivir con estas limitaciones, la exportación estática es suficiente.

Método 2: modo SSR (adaptador OpenNext)

Si necesitas API Routes, SSR, rutas dinámicas, etc., debes usar un adaptador. Es un poco más complejo, pero lo explico con claridad.

Instalar el adaptador:

npm install @opennextjs/cloudflare

Configurar next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  // no configures output: 'export'
  images: {
    unoptimized: true,
  },
}
module.exports = nextConfig

Configuración en Cloudflare Pages:

¡Importante! Configurar Compatibility Flags (donde más se falla):

Este paso es clave; mucha gente se queda aquí. La primera vez no lo configuré y apareció el error nodejs_compat is not defined.

1. Proyecto → Settings → Functions
2. Busca la sección Compatibility flags
3. Haz clic en Configure Production compatibility flag
4. Añade el flag: nodejs_compat
5. Configura Compatibility Date: al menos 2024-09-23 (o más reciente)

Nota:

• Configura Production y Preview
• Sin este flag, tras el despliegue verás error 500 directamente

Requisito Edge Runtime:

Si usas API Routes o Server Components, debes añadir la declaración Edge Runtime:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

// app/api/hello/route.js
export const runtime = 'edge'; // ¡clave! añade esta línea
export async function GET(request) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

// pages/api/hello.js (Pages Router)
export const config = {
  runtime: 'edge', // ¡clave! añade esta línea
};
export default function handler(req) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

Todos los archivos que se ejecuten en el servidor deben incluir esta declaración, si no el despliegue fallará.

Variables de entorno en Next.js

Las variables de entorno en Next.js se dividen en dos tipos:

1. Variables de cliente (prefijo obligatorio):

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Next.js Site

2. Variables de servidor (sin prefijo):

# .env.local
DATABASE_URL=postgresql://...
API_SECRET=your-secret-key

Configuración en Cloudflare Pages:

Entra en Settings → Environment variables y añade variables eligiendo el entorno (Production/Preview).

Uso en el código:

// Cliente
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
// Servidor (API Route o Server Component)
const dbUrl = process.env.DATABASE_URL;

Errores frecuentes de Next.js y soluciones (¡importante!)

Aquí recopilo 5 errores que más he visto y cómo resolverlos.

Error 1: nodejs_compat is not defined o error 500

Mensaje de error:

Error: The global scope does not support nodejs_compat

O el despliegue parece exitoso pero al abrir la página hay error 500.

Causa:

Falta el flag de compatibilidad nodejs_compat.

Solución:

1. Proyecto → Settings → Functions
2. Busca Compatibility flags
3. Añade nodejs_compat en Production y Preview
4. Vuelve a desplegar

A mí me costó un rato; en cuanto lo configuré, funcionó al instante.

Error 2: despliegue exitoso pero la página muestra 404

Síntomas:

• El log de build indica éxito
• Al visitar xxx.pages.dev aparece 404
• O solo la home funciona y el resto da 404

Causas:

• Edge Runtime mal configurado
• Build output directory incorrecto

Solución:

1. Comprueba que todas las API Routes y Server Components tengan runtime = 'edge'
2. Confirma que Build output directory sea .worker-next (con adaptador) u out (exportación estática)
3. En exportación estática, comprueba si creaste el archivo _redirects

Error 3: FinalizationRegistry is not defined

Mensaje de error:

ReferenceError: FinalizationRegistry is not defined

Causa:

Compatibility Date demasiado antigua; no soporta características JavaScript recientes.

Solución:

1. Settings → Functions
2. Actualiza Compatibility Date a 2024-09-23 o más reciente
3. Vuelve a desplegar

Error 4: build demasiado largo o fallido

Síntomas:

• El build tarda más de 10 minutos
• O aparece «Build exceeded maximum duration»

Causas:

• Uso de Turbopack (next dev --turbo)
• Proyecto muy grande con demasiadas dependencias

Solución:

1. Comprueba Build command: debe ser npx @opennextjs/cloudflare, sin parámetro --turbo
2. Limpia dependencias innecesarias: npm prune
3. Valora la exportación estática si te sirve

Error 5: error de Image Optimization

Mensaje de error:

Error: Image Optimization using Next.js' default loader is not compatible with `output: 'export'`.

Causa:

Cloudflare Pages no soporta la API de Image Optimization de Next.js.

Solución:

Desactívala en next.config.js:

module.exports = {
  images: {
    unoptimized: true,
  },
}

Si necesitas optimizar imágenes, puedes usar:

• Cloudflare Images (servicio de pago)
• CDN de terceros (como Cloudinary)
• Procesar imágenes tú mismo (comprimir antes de subir)

Gestión avanzada de variables de entorno

Al principio las variables de entorno me confundían, sobre todo cómo distinguir desarrollo, preview y producción. Con el tiempo encontré un método claro.

Distinguir los tres entornos

Cloudflare Pages soporta tres entornos:

Configuración en Cloudflare Dashboard

Proyecto → Settings → Environment variables

Verás dos pestañas:

• Production: variables de producción
• Preview: variables de preview

Configuración recomendada:

1. Variables de producción (API Key real, conexión a BD, etc.):
   • Tipo Secret (cifrado, no aparece en logs)
   • Ejemplo: API_KEY=prod-key-12345
2. Variables de preview (API Key de prueba):
   • Puede ser Plain text
   • Ejemplo: API_KEY=test-key-67890

Variables de entorno en desarrollo local

Estructura de archivos recomendada:

my-project/
├── .env.local          # variables locales (no subir a Git)
├── .env.example        # plantilla (sí subir a Git)
├── .gitignore          # ignorar archivos sensibles

Ejemplo de .env.local:

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

# Configuración API
VITE_API_BASE_URL=http://localhost:3000/api
VITE_API_KEY=local-dev-key
# Interruptores de funciones
VITE_ENABLE_DEBUG=true
VITE_ENABLE_ANALYTICS=false
# Servicios de terceros
VITE_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

Ejemplo de .env.example:

# Configuración API
VITE_API_BASE_URL=your-api-url-here
VITE_API_KEY=your-api-key-here
# Interruptores de funciones
VITE_ENABLE_DEBUG=false
VITE_ENABLE_ANALYTICS=true

Recordatorio importante:

• No subas .env.local a Git
• Sí sube .env.example para que el equipo tenga referencia
• Añade en .gitignore: .env*.local

Tabla rápida de prefijos de variables de entorno

Los prefijos varían según el framework; aquí tienes una tabla de referencia:

Truco para recordar:

• Si la variable se lee en el navegador, lleva prefijo
• Si solo se usa en el servidor (API Key, contraseña de BD), no lleva prefijo

¿Cómo depurar variables que no surten efecto?

He tenido varias veces variables configuradas que no funcionaban. Aquí va una checklist:

Pasos de depuración:

1. Comprueba el prefijo
   • ¿Proyecto Vite con prefijo REACT_APP_? (debería ser VITE_)
   • ¿Variables de cliente Next.js sin NEXT_PUBLIC_?
2. Confirma que redeployaste
   • Tras modificar variables debes lanzar un nuevo despliegue
   • Haz un push pequeño a Git o pulsa «Retry deployment» en el Dashboard
3. Verifica el entorno correcto
   • ¿Modificaste Production pero accedes al enlace Preview?
   • ¿O al revés?
4. Revisa los logs de build
   • Busca el nombre de la variable
   • Confirma que se lee correctamente (las Secret no muestran el valor)
5. Comprueba la referencia en el código

   // ❌ Incorrecto (proyecto Vite)
   const apiUrl = process.env.VITE_API_URL;
   // ✅ Correcto (proyecto Vite)
   const apiUrl = import.meta.env.VITE_API_URL;
   

Técnicas avanzadas y buenas prácticas

Desplegar con éxito es solo el primer paso; estas técnicas harán tu proyecto más profesional.

Vincular un dominio personalizado

El dominio xxx.pages.dev no transmite mucha confianza; vincular tu propio dominio es sencillo.

Pasos:

1. Añadir dominio en Cloudflare Pages:
   • Proyecto → Custom domains
   • Haz clic en Set up a custom domain
   • Introduce tu dominio (ej. blog.example.com)
2. Configurar registro DNS:
   • Si el dominio ya está en Cloudflare, se añade el CNAME automáticamente
   • Si el dominio está en otro proveedor, añádelo manualmente:

     CNAME  blog  your-project.pages.dev
     

3. Esperar la generación del certificado SSL:
   • Cloudflare solicita un certificado SSL gratuito
   • Suele tardar 5-10 minutos

Después podrás acceder con tu dominio y HTTPS automático.

Preview Deployments (despliegues de preview)

Esta función encaja muy bien con el trabajo en equipo. Cada push a una rama distinta de la principal o cada Pull Request crea un entorno de preview automáticamente.

Cómo usarlo:

1. Crea una rama nueva:

   git checkout -b feature/new-button
   

2. Modifica el código y haz push:

   git add .
   git commit -m "Add new button"
   git push origin feature/new-button
   

3. CF Pages construye y genera un enlace de preview:

   https://abc123.your-project.pages.dev
   

4. Revisa el enlace de preview en el PR y prueba la función nueva
5. Al fusionar a la rama principal, se despliega automáticamente a producción

Ventajas:

• Cada rama de funcionalidad tiene su propio entorno de preview
• Product managers y diseñadores pueden ver el resultado directamente
• No afecta al entorno de producción

Optimización de caché de build

Si cada build tarda mucho, prueba optimizar la caché.

Añadir configuración de caché en el proyecto:

Cloudflare Pages cachea node_modules automáticamente, pero puedes ir más allá:

1. Usar pnpm (más rápido que npm):

   # Añade .npmrc al proyecto
   echo "package-manager=pnpm" > .npmrc
   

2. Configurar en CF Pages:
   • Cambia Build command a: pnpm install && pnpm build
3. Eliminar dependencias innecesarias:

   npm prune
   

Mi experiencia:

Tras cambiar a pnpm, el tiempo de build bajó de 5 minutos a 2; la diferencia se nota.

Configurar headers personalizados

Si quieres añadir HTTP headers personalizados (política de seguridad, control de caché), crea un archivo _headers en la raíz del proyecto:

# Ejemplo de archivo _headers
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: no-referrer-when-downgrade
/static/*
  Cache-Control: public, max-age=31536000, immutable
/api/*
  Cache-Control: no-cache

Guarda y vuelve a desplegar; los headers entrarán en vigor.

Resumen

En resumen, todo se reduce a tres puntos:

1. Entiende la configuración de build de tu proyecto

• ¿Cuál es el Build command? (normalmente npm run build)
• ¿Dónde está el directorio de salida? (Vite: dist, CRA: build, Next.js según el modo)
• ¿Qué variables de entorno necesitas? (atención a los prefijos)

2. Cuidado con las trampas frecuentes

• Flag nodejs_compat en Next.js (sin él, error 500)
• Prefijos de variables de entorno (Vite usa VITE_, Next usa NEXT_PUBLIC_)
• 404 en rutas SPA (recuerda el archivo _redirects)

3. Aprovecha el entorno Preview

• No pruebes directamente en producción
• Crea un entorno Preview con una rama
• Fusiona a la rama principal solo cuando todo funcione

Cloudflare Pages no es tan difícil; la primera configuración lleva tiempo, pero una vez lista basta con git push para desplegar automáticamente.

Y el tráfico ilimitado gratis es una ventaja enorme: tengo varios proyectos personales en CF Pages sin ansiedad por el tráfico.

Si tienes problemas:

• Revisa la sección de errores frecuentes; la mayoría ya las he pisado yo
• Mira los logs de build; el mensaje de error suele indicar qué falló
• La documentación oficial está en inglés pero es detallada: Cloudflare Pages Docs

Próximos pasos:

• Despliega tu primer proyecto en Cloudflare Pages
• Prueba a vincular un dominio personalizado
• Experimenta con Preview Deployments

Si tienes dudas, déjalas en los comentarios; las revisaré. ¡Buen despliegue!