🎨 Sysprovider Code
Sysprovider LogoWiki
🇪🇸Hosting español para ecommerce

Implementación de Headless WordPress con Next.js y GraphQL

Actualizado el 30 de enero de 2026

La arquitectura headless WordPress ha evolucionado de ser una tendencia a convertirse en un estándar para proyectos que exigen rendimiento extremo, escalabilidad y libertad creativa en el frontend. Combinar WordPress como gestor de contenidos (CMS) con Next.js como framework de React y GraphQL como capa de comunicación es la combinación más potente y moderna para el stack JAMstack en 2025. Este artículo es una guía técnica completa para implementar esta arquitectura, cubriendo desde la configuración inicial hasta la optimización para producción.

¿Por qué Headless WordPress con Next.js y GraphQL?

El enfoque tradicional de WordPress (monolítico) mezcla la capa de presentación (PHP + temas) con la lógica de negocio. Esto genera limitaciones en rendimiento, seguridad y flexibilidad. Al separar el frontend (Next.js) del backend (WordPress), obtenemos ventajas clave:

  • Rendimiento extremo: Next.js genera HTML estático (SSG) o renderiza del lado del servidor (SSR) con revalidación incremental (ISR). El resultado son páginas que cargan en milisegundos.
  • Mejor experiencia de desarrollo: Usamos React, TypeScript, Tailwind CSS o cualquier librería moderna. El frontend es una aplicación web progresiva (PWA) nativa.
  • Seguridad mejorada: Al no exponer WordPress directamente al usuario, reducimos la superficie de ataque. El fronten estático o servido desde un CDN es mucho más seguro.
  • Escalabilidad sin límites: El frontend puede servirse desde Vercel, Netlify o Cloudflare Pages, mientras que WordPress se aloja en un servidor mínimo o incluso en una instancia serverless.
  • GraphQL como puente: A diferencia de la REST API de WordPress, GraphQL permite consultas precisas, evitando el over-fetching y under-fetching. Solo pedimos los datos que necesitamos.

[INFO] Aunque la REST API de WordPress es funcional, GraphQL reduce drásticamente el tamaño de las respuestas y simplifica las consultas complejas (relaciones entre posts, campos personalizados, ACF, etc.).

Configuración Inicial del Backend (WordPress Headless)

El primer paso es preparar WordPress para funcionar como un CMS headless. No necesitas un tema visual, solo el núcleo y los plugins adecuados.

1. Instalación de WordPress y Plugins Esenciales

Instala WordPress en un servidor (puede ser local con LocalWP, o en un VPS mínimo). Luego, instala estos plugins:

  • WPGraphQL: Expone los datos de WordPress mediante un endpoint GraphQL (/graphql). Es el corazón de la comunicación.
  • Advanced Custom Fields (ACF) + WPGraphQL for ACF: Si usas campos personalizados (recomendado para contenido estructurado), este plugin los expone en GraphQL.
  • Yoast SEO o Rank Math: Para gestionar metadatos SEO desde WordPress. Ambos tienen integración con WPGraphQL.
  • Custom Post Type UI (CPT UI): Para crear tipos de contenido personalizados (por ejemplo, proyectos, testimonios).
  • WPGraphQL JWT Authentication: Para manejar autenticación (por ejemplo, para borradores o contenido privado).

2. Configuración de Permalinks y CORS

Asegúrate de que los enlaces permanentes estén en formato "Nombre de la entrada" (Post name). Luego, configura CORS en el archivo wp-config.php para permitir peticiones desde tu frontend:

// wp-config.php
header("Access-Control-Allow-Origin: https://tudominio-frontend.com");
header("Access-Control-Allow-Methods: GET, POST, OPTIONS");
header("Access-Control-Allow-Headers: Content-Type, Authorization");

[WARNING] No uses Access-Control-Allow-Origin: * en producción. Especifica siempre tu dominio del frontend para evitar vulnerabilidades CSRF.

3. Creación de Contenido con GraphQL en Mente

Cuando crees contenido, piensa en cómo lo consumirá Next.js. Usa ACF para crear grupos de campos que representen bloques de contenido (hero, tarjetas, testimonios). Esto permite que el editor visual de WordPress sea intuitivo, mientras que el frontend recibe datos perfectamente estructurados.

Configuración del Frontend con Next.js

Ahora pasamos al lado del frontend. Usaremos Next.js 14+ con App Router y TypeScript.

1. Creación del Proyecto e Instalación de Dependencias

npx create-next-app@latest headless-wp-nextjs --typescript --tailwind --app
cd headless-wp-nextjs
npm install @apollo/client graphql

2. Configuración del Cliente Apollo (GraphQL)

Crea un archivo lib/apollo-client.ts para configurar el cliente Apollo:

import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';

const httpLink = createHttpLink({
  uri: 'https://tudominio-wp.com/graphql', // Endpoint de WPGraphQL
});

const client = new ApolloClient({
  link: httpLink,
  cache: new InMemoryCache(),
  ssrMode: typeof window === 'undefined', // Importante para SSR/SSG
});

export default client;

3. Consulta GraphQL para Obtener Posts

Define una consulta en lib/queries.ts:

import { gql } from '@apollo/client';

export const GET_POSTS = gql`
  query GetPosts {
    posts(first: 10) {
      nodes {
        id
        title
        slug
        excerpt
        date
        featuredImage {
          node {
            sourceUrl
            altText
          }
        }
        categories {
          nodes {
            name
            slug
          }
        }
      }
    }
  }
`;

4. Página Principal con SSG (Static Site Generation)

Crea app/page.tsx:

import client from '@/lib/apollo-client';
import { GET_POSTS } from '@/lib/queries';
import Link from 'next/link';

export default async function Home() {
  const { data } = await client.query({ query: GET_POSTS });

  return (
    <main className="container mx-auto py-10">
      <h1 className="text-4xl font-bold mb-8">Blog Headless WordPress</h1>
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
        {data.posts.nodes.map((post: any) => (
          <article key={post.id} className="border rounded-lg p-4 shadow-sm">
            {post.featuredImage && (
              <img
                src={post.featuredImage.node.sourceUrl}
                alt={post.featuredImage.node.altText || post.title}
                className="w-full h-48 object-cover rounded-t-lg"
              />
            )}
            <h2 className="text-2xl font-semibold mt-4">{post.title}</h2>
            <p className="text-gray-600 mt-2">{post.excerpt}</p>
            <Link href={`/posts/${post.slug}`} className="text-blue-600 hover:underline mt-4 block">
              Leer más →
            </Link>
          </article>
        ))}
      </div>
    </main>
  );
}

[TIP] Para usar SSG con Next.js App Router, las consultas se ejecutan en el servidor durante el build. Si necesitas datos en tiempo real (por ejemplo, para un dashboard), usa 'use client' y Apollo Client del lado del cliente.

Optimización para el Stack JAMstack en 2025

Para que tu implementación sea realmente profesional y esté preparada para 2025, debes considerar estos puntos críticos.

1. Revalidación Incremental (ISR) para Contenido Dinámico

No necesitas reconstruir todo el sitio cada vez que publicas un post. Usa ISR para regenerar páginas específicas bajo demanda:

// app/posts/[slug]/page.tsx
export const revalidate = 60; // Revalida cada 60 segundos

export default async function PostPage({ params }: { params: { slug: string } }) {
  const { data } = await client.query({
    query: GET_POST_BY_SLUG,
    variables: { slug: params.slug },
  });

  // Renderizar post...
}

O mejor aún, usa On-Demand Revalidation con webhooks desde WordPress:

  1. Cuando actualizas un post, WordPress envía un webhook a una API route de Next.js.
  2. Esa ruta llama a revalidatePath('/posts/mi-post') o revalidateTag('posts').
  3. La página se regenera instantáneamente sin rebuild completo.

2. Manejo de Imágenes con Next.js Image

Next.js ofrece un componente <Image> que optimiza imágenes automáticamente (WebP, lazy loading, redimensionado). Para usarlo con imágenes de WordPress, configura next.config.js:

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'tudominio-wp.com',
        port: '',
        pathname: '/wp-content/uploads/**',
      },
    ],
  },
};

Luego, en tu componente:

import Image from 'next/image';

<Image
  src={post.featuredImage.node.sourceUrl}
  alt={post.featuredImage.node.altText}
  width={800}
  height={450}
  className="rounded-t-lg"
/>

3. Autenticación y Contenido Privado

Si necesitas mostrar borradores o contenido premium, usa JWT Authentication:

  1. En WordPress, instala y activa el plugin WPGraphQL JWT Authentication.
  2. En Next.js, crea un formulario de login que envíe credenciales al endpoint /graphql con la mutación login.
  3. Almacena el token en cookies HTTP-only (usando Next.js API Routes).
  4. En las consultas GraphQL que requieran autenticación, incluye el header Authorization: Bearer <token>.
// app/api/login/route.ts
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const { username, password } = await request.json();
  const response = await fetch('https://tudominio-wp.com/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `mutation Login($username: String!, $password: String!) {
        login(input: { username: $username, password: $password }) {
          authToken
          user { id name }
        }
      }`,
      variables: { username, password },
    }),
  });

  const data = await response.json();
  // Guardar token en cookie...
}

4. SEO Técnico con Next.js y GraphQL

Para que Google indexe correctamente tu sitio headless:

  • Metadatos dinámicos: Usa la API generateMetadata de Next.js App Router para inyectar title, description y Open Graph tags desde los datos de WordPress (incluyendo campos de Yoast/Rank Math expuestos en GraphQL).
  • Sitemap dinámico: Genera un sitemap.xml con Next.js que incluya todas las URLs de posts, páginas y CPTs. Esto se puede hacer con una ruta app/sitemap.ts.
  • Robots.txt: Configura app/robots.ts para indicar a los crawlers las rutas permitidas.
// app/sitemap.ts
import { client } from '@/lib/apollo-client';
import { GET_ALL_POSTS_SLUGS } from '@/lib/queries';

export default async function sitemap() {
  const { data } = await client.query({ query: GET_ALL_POSTS_SLUGS });
  const posts = data.posts.nodes.map((post: any) => ({
    url: `https://tudominio.com/posts/${post.slug}`,
    lastModified: new Date(post.date),
    changeFrequency: 'weekly',
    priority: 0.8,
  }));

  return [
    { url: 'https://tudominio.com', lastModified: new Date(), changeFrequency: 'daily', priority: 1 },
    ...posts,
  ];
}

Despliegue y CI/CD para Producción

El stack headless brilla cuando se despliega en plataformas serverless.

1. Despliegue de WordPress

Puedes alojar WordPress en:

  • WP Engine o Kinsta: Ofrecen hosting optimizado para headless con caché GraphQL.
  • VPS con Docker: Para mayor control, usa docker-compose con WordPress + MariaDB + Nginx.
  • Serverless WordPress: Plataformas como WordPress.com Developer o SpinupWP permiten instancias ligeras.

2. Despliegue de Next.js

La opción más común es Vercel (creadores de Next.js). Conecta tu repositorio de GitHub y configura las variables de entorno:

NEXT_PUBLIC_WP_URL=https://tudominio-wp.com

Cada git push a la rama principal dispara un build que genera páginas estáticas (SSG) y las sirve desde el CDN global de Vercel.

[INFO] Si tu sitio tiene mucho contenido dinámico (comentarios en tiempo real, carrito de compras), considera usar Next.js con SSR y caching en Vercel Edge Functions para minimizar la latencia.

3. Webhooks para Actualización Automática

Configura un webhook en WordPress (usando un plugin como WP Webhooks o Zapier) que notifique a Vercel cada vez que se publique o actualice contenido. Vercel expone un endpoint de revalidación que puedes llamar:

POST https://api.vercel.com/v1/integrations/deploy/PROJECT_ID/TRIGGER_TOKEN

Esto asegura que tu frontend esté siempre sincronizado con el contenido de WordPress sin necesidad de reconstruir todo el sitio.

Conclusión: El Futuro es Headless

Implementar headless WordPress con Next.js y GraphQL no es solo una moda técnica, es una decisión estratégica para 2025. Separas la gestión de contenido del frontend, obtienes rendimiento de clase mundial (puntuaciones Lighthouse de 95+), y mantienes la flexibilidad de WordPress que los editores aman.

El stack JAMstack (JavaScript, APIs, Markup) con WordPress como headless CMS te permite:

  • Entregar sitios ultra rápidos.
  • Escalar sin preocuparte por el servidor.
  • Usar las mejores herramientas modernas (React, TypeScript, Tailwind).
  • Mantener un flujo de trabajo de desarrollo eficiente con Git y CI/CD.

Si estás empezando un proyecto nuevo o migrando uno existente, esta arquitectura es la inversión correcta. WordPress no muere, se transforma en el mejor headless CMS del mercado.

¿Necesitas ayuda?Son dos de nuestros técnicos, Agustín y Mikel, y están disponibles para resolver cualquier problema.

Hablar con ellos ahora
Agustín y Mikel