Domina las Transiciones Headless en WordPress: Guía de WPGraphQL y Next.js

Introducción al Desarrollo Headless con WordPress 🚀

El desarrollo web evoluciona constantemente, y la arquitectura headless (o desacoplada) se ha convertido en el estándar de oro para crear experiencias digitales de alto rendimiento. En una configuración tradicional de WordPress, el CMS se encarga tanto de gestionar el contenido (backend) como de mostrarlo a los visitantes (frontend). Al desacoplar WordPress, utilizamos el CMS exclusivamente como un potente backend de gestión de contenidos, mientras que delegamos la interfaz de usuario en tecnologías modernas de JavaScript como Next.js.

Esta separación ofrece ventajas masivas: velocidades de carga excepcionales, mayor seguridad al reducir la superficie de ataque y una flexibilidad de diseño absoluta para los desarrolladores de frontend. A lo largo de este tutorial, configuraremos un entorno completo conectando WordPress con Next.js utilizando WPGraphQL.

¿Por qué Elegir la Combinación de WordPress y Next.js? 🎯

Antes de sumergirnos en el código, es fundamental entender por qué esta pila tecnológica es tan potente. Tradicionalmente, la API REST de WordPress ha sido la herramienta por defecto para el desarrollo headless. Sin embargo, la API REST sufre a menudo de problemas de sobre-recuperación (over-fetching) o sub-recuperación (under-fetching) de datos. GraphQL resuelve esto permitiendo que el cliente solicite exactamente los datos que necesita y nada más.

Requisitos Previos y Configuración del Entorno 🛠️

Para completar este tutorial con éxito, asegúrate de tener las siguientes herramientas instaladas en tu ordenador:

• Requisito Node.js (versión 18.x o superior)
• Requisito Un entorno local de WordPress (LocalWP, XAMPP o Docker)
• Requisito Editor de código (recomendado: VS Code)

Paso 1: Configuración del Backend en WordPress

Lo primero que debemos hacer es preparar nuestro sitio de WordPress para que exponga su contenido a través de GraphQL.

Instalación de WPGraphQL

1. Inicia sesión en el panel de administración de tu sitio WordPress.
2. Dirígete a Plugins > Añadir nuevo.
3. Busca "WPGraphQL" en el buscador de plugins.
4. Haz clic en Instalar ahora y posteriormente en Activar.

Una vez activado, verás un nuevo menú en el panel de control llamado GraphQL. Al hacer clic en él, accederás a la herramienta interactiva GraphiQL IDE, que te permite probar consultas directamente en tu navegador.

Verificación del Endpoint

Por defecto, tu endpoint de GraphQL estará disponible en la siguiente URL:

http://tu-sitio-wordpress.local/index.php?graphql

O si tienes activadas las URLs amigables (Permalinks):

http://tu-sitio-wordpress.local/graphql

Paso 2: Creación de la Aplicación Next.js

Ahora que nuestro backend está listo para transmitir datos, vamos a configurar el frontend utilizando Next.js con el sistema de App Router.

Abre tu terminal y ejecuta el siguiente comando para crear un nuevo proyecto:

npx create-next-app@latest my-wordpress-headless

Durante la instalación, te recomendamos seleccionar las siguientes opciones para mantener la compatibilidad con este tutorial:

• ¿Deseas usar TypeScript? Sí (o No, según tu preferencia)
• ¿Deseas usar ESLint? Sí
• ¿Deseas usar Tailwind CSS? Sí
• ¿Deseas usar el directorio src/? Sí
• ¿Deseas usar App Router? Sí

Una vez finalizada la instalación, navega a la carpeta del proyecto e inicia el servidor de desarrollo:

cd my-wordpress-headless
npm run dev

Paso 3: Conexión y Consulta de Datos con GraphQL

Para conectar Next.js con WordPress, crearemos una función de utilidad que realice peticiones HTTP POST al endpoint de GraphQL.

Creación del Cliente de Consultas

Crea un archivo llamado lib/api.js (o lib/api.ts si usas TypeScript) dentro de la carpeta src de tu proyecto Next.js e introduce el siguiente código:

const API_URL = process.env.WORDPRESS_API_URL;

async function fetchAPI(query, { variables } = {}) {
  const headers = { 'Content-Type': 'application/json' };

  const res = await fetch(API_URL, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      query,
      variables,
    }),
  });

  const json = await res.json();
  if (json.errors) {
    console.error(json.errors);
    throw new Error('Falló al conectar con la API de GraphQL.');
  }
  return json.data;
}

export async function getAllPosts() {
  const data = await fetchAPI(`
    {
      posts {
        nodes {
          id
          title
          slug
          date
          excerpt
        }
      }
    }
  `);
  return data?.posts?.nodes;
}

No olvides crear un archivo .env.local en la raíz de tu proyecto Next.js para definir tu variable de entorno:

WORDPRESS_API_URL=http://tu-sitio-wordpress.local/graphql

Paso 4: Renderizado de las Entradas en Next.js

Con la función getAllPosts lista, ahora podemos consumirla en nuestra página principal para mostrar una lista dinámica de las publicaciones obtenidas directamente desde WordPress.

Modifica el archivo src/app/page.js (o page.tsx) con el siguiente contenido:

import { getAllPosts } from '@/lib/api';
import Link from 'next/link';

export default async function Home() {
  const posts = await getAllPosts();

  return (
    <main className="max-w-4xl mx-auto p-6">
      <h1 className="text-4xl font-bold mb-8 text-center">
        Mi Blog Headless con WordPress y Next.js
      </h1>
      <div className="grid gap-6">
        {posts.map((post) => (
          <article key={post.id} className="p-6 border rounded-lg shadow-sm bg-white">
            <h2 className="text-2xl font-semibold mb-2">
              <Link href={`/posts/${post.slug}`} className="text-blue-600 hover:underline">
                {post.title}
              </Link>
            </h2>
            <p className="text-gray-500 text-sm mb-4">
              {new Date(post.date).toLocaleDateString()}
            </p>
            <div 
              className="text-gray-700" 
              dangerouslySetInnerHTML={{ __html: post.excerpt }} 
            />
          </article>
        ))}
      </div>
    </main>
  );
}

Preguntas Frecuentes (FAQ)

Conclusión y Próximos Pasos 🌟

¡Felicidades! Has configurado con éxito una arquitectura headless moderna combinando la versatilidad de gestión de contenidos de WordPress con la velocidad y potencia de Next.js y WPGraphQL.

Para seguir mejorando tus habilidades en este ecosistema, te recomendamos explorar los siguientes temas avanzados:

• Implementación de Incremental Static Regeneration (ISR) en Next.js para actualizar contenido sin reconstruir todo el sitio.
• Consulta de tipos de contenido personalizado (Custom Post Types) y campos avanzados con ACF (Advanced Custom Fields) integrado en WPGraphQL.
• Configuración de vistas previas en tiempo réel (Preview Mode) para editores de WordPress.