Cómo implementar headless WordPress + Next.js

Qué vas a lograr

Un sitio donde el equipo de contenido sigue usando WordPress como siempre, pero el frontend es Next.js (React) con rendimiento significativamente superior. El sitio se pre-genera estáticamente, se sirve desde CDN global y tiene 95+ en PageSpeed. Ideal para sitios con tráfico alto o requisitos de performance estrictos.

Requisitos previos

• WordPress instalado y funcionando (puede ser hosting estándar)
• Node.js 18+ instalado localmente
• Conocimiento básico de React y GraphQL (no necesitas ser experto)
• Cuenta en Vercel (gratuita para proyectos personales)
• Acceso admin a WordPress para instalar plugins

Paso 1 — Configurar WordPress como headless CMS

1. Instala plugin WPGraphQL en WordPress → buscar en Plugins → Add New
2. Activa WPGraphQL: ahora tienes endpoint GraphQL en tusitio.com/graphql
3. Instala también WPGraphQL for ACF si usas Advanced Custom Fields para exponer esos campos via GraphQL
4. Verifica el endpoint abriendo tusitio.com/graphql en el navegador (debe retornar JSON)
5. Usa el IDE integrado de WPGraphQL (GraphiQL) en wp-admin → GraphQL → GraphiQL para explorar el schema y probar queries

Paso 2 — Crear proyecto Next.js

1. En terminal: npx create-next-app@latest mi-sitio-headless
2. Selecciona: TypeScript YES, App Router YES, Tailwind CSS YES
3. Instala dependencias: npm install graphql-request graphql
4. Crea archivo .env.local con WORDPRESS_API_URL=https://tu-wordpress.com/graphql

Paso 3 — Configurar queries GraphQL para posts

// lib/queries.ts
import { request } from 'graphql-request';

const GET_ALL_POSTS = `
  query GetAllPosts {
    posts(first: 100) {
      nodes {
        id
        slug
        title
        excerpt
        date
        featuredImage { node { sourceUrl } }
      }
    }
  }
`;

export async function getAllPosts() {
  const data = await request(
    process.env.WORDPRESS_API_URL!,
    GET_ALL_POSTS
  );
  return data.posts.nodes;
}

Paso 4 — Implementar ISR para performance óptimo

// app/blog/[slug]/page.tsx
export const revalidate = 3600; // re-generar cada hora

export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map(post => ({ slug: post.slug }));
}

export default async function PostPage({ params }) {
  const post = await getPostBySlug(params.slug);
  return <article>{post.content}</article>;
}

1. ISR pre-genera todas las páginas en build time y las re-genera en background cada hora
2. Los visitantes siempre reciben páginas pre-generadas desde CDN de Vercel

Verificación y troubleshooting

• Error CORS: en WordPress, agrega header Access-Control-Allow-Origin en .htaccess o via plugin
• Imágenes no cargan: en Next.js next.config.js agrega tu dominio de WordPress en images.remotePatterns
• Queries muy lentas: activa caché de WPGraphQL en Settings → WPGraphQL → Performance
• Contenido no se actualiza: el revalidate de ISR define cada cuánto re-genera. Usa on-demand revalidation via webhook de WordPress para regeneración inmediata al publicar

Próximos pasos y optimización

• Preview Mode: implementa draft preview para que el equipo editorial vea borradores antes de publicar
• SEO: instala next-seo y expone yoast_head_json via WPGraphQL para mantener el SEO de Yoast
• Deployment: conecta el repo de GitHub a Vercel para deploy automático en cada push

En Weblindrome ofrecemos Desarrollo web para ayudarte con esta y otras implementaciones. Solicita una cotización personalizada.