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

Implementación de Headless WordPress con Next.js 2025

Actualizado el 12 de junio de 2026

El ecosistema de desarrollo web ha experimentado una transformación radical en los últimos años, y una de las arquitecturas que más ha resonado en la comunidad de WordPress es el enfoque headless. Combinar un backend robusto como WordPress con un frontend ultrarrápido y moderno como Next.js ya no es una tendencia, sino una necesidad para proyectos que buscan escalabilidad, rendimiento y seguridad.

En 2025, esta implementación ha madurado hasta el punto de ser considerada el estándar de facto para sitios de alto tráfico, aplicaciones web progresivas (PWA) y portales editoriales. A continuación, te ofrezco una guía técnica completa, paso a paso, para implementar un Headless WordPress con Next.js, aprovechando al máximo la WordPress API REST y los principios de la arquitectura headless dentro del ecosistema JAMstack.

¿Por qué Headless WordPress con Next.js en 2025?

La combinación de WordPress como CMS headless y Next.js como framework de frontend resuelve los problemas clásicos de los sitios WordPress tradicionales: tiempos de carga lentos, dependencia del servidor PHP y limitaciones en la experiencia de desarrollo.

Al separar el frontend del backend, obtienes:

  • Rendimiento extremo: Next.js genera páginas estáticas (SSG) o renderiza bajo demanda (ISR) desde el servidor Node.js, ofreciendo puntuaciones perfectas en Core Web Vitals.
  • Seguridad mejorada: Al exponer únicamente la WordPress API REST (o GraphQL), reduces drásticamente la superficie de ataque. No hay PHP ejecutándose en el frontend.
  • Flexibilidad total: Puedes consumir datos de múltiples fuentes (WordPress, Stripe, CMS headless) en una sola aplicación Next.js.
  • Escalabilidad: El frontend se despliega en CDNs globales (Vercel, Netlify), mientras que el backend WordPress puede vivir en un servidor modesto.

[INFO] Esta arquitectura es ideal para proyectos que requieren una experiencia de usuario premium, como tiendas online, periódicos digitales o aplicaciones SaaS con contenido dinámico.

Preparando el Entorno: WordPress como Backend Headless

Antes de tocar una línea de código en Next.js, debemos configurar WordPress para que funcione exclusivamente como un proveedor de contenido (API).

Instalación y Configuración de WordPress

  1. Instalación limpia: Usa una instalación estándar de WordPress (preferiblemente en un subdominio como api.tudominio.com o en un contenedor Docker).
  2. Permalinks: Ve a Ajustes > Enlaces permanentes y selecciona cualquier estructura que no sea la "Simple". Recomiendo usar el formato de entrada (/%postname%/). Esto es crucial para que la API REST funcione correctamente.
  3. Plugins esenciales (opcionales pero recomendados):
    • WPGraphQL: Si prefieres GraphQL en lugar de la REST API. Para este artículo, nos centraremos en la REST API, que es nativa.
    • ACF (Advanced Custom Fields): Para crear campos personalizados y exponerlos a través de la API. Es casi obligatorio en proyectos headless.
    • Yoast SEO o Rank Math: Aunque el frontend maneja el SEO técnico, estos plugins ayudan a estructurar los metadatos en la respuesta de la API.
    • CORS (Cross-Origin Resource Sharing): Instala un plugin como "WP Headless CORS" para permitir peticiones desde tu dominio de Next.js.

Configuración de la API REST

WordPress expone por defecto la API REST en la ruta /wp-json/wp/v2/. Para un uso headless, es recomendable deshabilitar el frontend público de WordPress para evitar que los usuarios accedan a /wp-admin o a las URLs de las entradas.

Añade el siguiente código al archivo wp-config.php:

// Deshabilitar el frontend de WordPress
define('WP_USE_THEMES', false);

// Redirigir cualquier petición no API a la API
add_action('init', function() {
    if ( ! defined('REST_REQUEST') || ! REST_REQUEST ) {
        wp_redirect( home_url('/wp-json/') );
        exit;
    }
});

[WARNING] Deshabilitar el frontend puede romper algunos plugins que dependen de la carga del tema. Asegúrate de probar en un entorno de staging.

Construyendo el Frontend con Next.js

Con el backend listo, pasamos a la parte divertida: crear la aplicación Next.js que consumirá la WordPress API REST.

Inicialización del Proyecto

npx create-next-app@latest headless-wp-next --typescript --tailwind --eslint
cd headless-wp-next

Eliminaremos el contenido de src/app/page.tsx y crearemos nuestra estructura de carpetas:

/src
  /app
    /posts
      [slug].tsx
    /api
      revalidate.ts
  /components
    PostCard.tsx
    Layout.tsx
  /lib
    api.ts

Configuración del Cliente API (lib/api.ts)

Crearemos un módulo centralizado para interactuar con la WordPress API REST. Aquí definiremos la URL base y las funciones para obtener posts, páginas y metadatos.

const API_URL = process.env.NEXT_PUBLIC_WORDPRESS_API_URL;

if (!API_URL) {
  throw new Error('Define NEXT_PUBLIC_WORDPRESS_API_URL en tu .env.local');
}

export async function fetchAPI(endpoint: string, params?: Record<string, string>) {
  const url = new URL(`${API_URL}/wp/v2/${endpoint}`);
  
  if (params) {
    Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));
  }

  const response = await fetch(url.toString(), {
    headers: { 'Content-Type': 'application/json' },
  });

  if (!response.ok) {
    throw new Error(`API Error: ${response.statusText}`);
  }

  return response.json();
}

export async function getPosts() {
  const posts = await fetchAPI('posts', { _embed: 'true', per_page: '10' });
  return posts;
}

export async function getPostBySlug(slug: string) {
  const posts = await fetchAPI('posts', { slug, _embed: 'true' });
  return posts[0] || null;
}

[TIP] El parámetro _embed es crucial. Le dice a la API que incluya los datos de las imágenes destacadas, autores y taxonomías directamente en la respuesta, evitando llamadas adicionales.

Página Principal con Static Site Generation (SSG)

Usaremos SSG para generar la página de inicio en tiempo de compilación. Next.js generará HTML estático para cada post.

// src/app/page.tsx
import { getPosts } from '@/lib/api';
import PostCard from '@/components/PostCard';

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

  return (
    <main className="container mx-auto px-4 py-8">
      <h1 className="text-4xl font-bold mb-8">Últimos artículos</h1>
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
        {posts.map((post: any) => (
          <PostCard key={post.id} post={post} />
        ))}
      </div>
    </main>
  );
}

Página de Post Individual con ISR (Incremental Static Regeneration)

Para los posts individuales, usaremos ISR. Esto genera la página estática en el primer acceso y la revalida cada cierto tiempo (por ejemplo, cada 60 segundos). Si el editor actualiza el contenido en WordPress, la página se regenerará sin necesidad de reconstruir todo el sitio.

// src/app/posts/[slug]/page.tsx
import { getPostBySlug, getPosts } from '@/lib/api';
import { notFound } from 'next/navigation';

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

export default async function PostPage({ params }: { params: { slug: string } }) {
  const post = await getPostBySlug(params.slug);

  if (!post) {
    notFound();
  }

  const featuredImage = post._embedded?.['wp:featuredmedia']?.[0]?.source_url || '/default.jpg';

  return (
    <article className="max-w-3xl mx-auto py-8">
      
      <h1 className="text-3xl font-bold mb-4" dangerouslySetInnerHTML={{ __html: post.title.rendered }} />
      <div className="prose prose-lg max-w-none" dangerouslySetInnerHTML={{ __html: post.content.rendered }} />
    </article>
  );
}

// Revalidar cada 60 segundos
export const revalidate = 60;

Gestión de Caché y Revalidación en Tiempo Real

Uno de los mayores desafíos en la arquitectura headless es mantener la sincronía entre el contenido editado en WordPress y el frontend estático. La solución es la Revalidación On-Demand.

Webhook de WordPress a Next.js

Cuando un editor publica o actualiza un post en WordPress, podemos enviar una petición a una API route de Next.js para que invalide la caché de ese post específico.

  1. Crea la API Route en Next.js:
// src/app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-revalidate-secret');

  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ message: 'Invalid secret' }, { status: 401 });
  }

  const body = await request.json();
  const slug = body?.slug;

  if (slug) {
    revalidatePath(`/posts/${slug}`);
    return NextResponse.json({ revalidated: true });
  }

  return NextResponse.json({ revalidated: false });
}
  1. Configura el Webhook en WordPress: Instala un plugin como "WP Webhooks" o "Zapier" y configura un webhook que envíe un POST a https://tudominio.com/api/revalidate con el slug del post y el header x-revalidate-secret.

[INFO] Esta arquitectura permite que el contenido se actualice en segundos, manteniendo las ventajas del SSG (velocidad) sin el estancamiento del contenido.

Optimización SEO y Rendimiento en la Arquitectura JAMstack

El enfoque JAMstack (JavaScript, APIs, Markup) se beneficia enormemente de la separación de responsabilidades. Para que tu sitio sea encontrado y vuele, sigue estas prácticas:

Metadatos Dinámicos con Next.js Metadata API

Aprovecha la API de metadatos de Next.js 14+ para generar etiquetas <title>, <meta> y Open Graph directamente desde los datos de WordPress.

// En src/app/posts/[slug]/page.tsx
import type { Metadata } from 'next';

export async function generateMetadata({ params }: { params: { slug: string } }): Promise<Metadata> {
  const post = await getPostBySlug(params.slug);
  
  if (!post) return { title: 'Post no encontrado' };

  return {
    title: post.title.rendered,
    description: post.excerpt.rendered.replace(/<[^>]*>/g, '').slice(0, 160),
    openGraph: {
      title: post.title.rendered,
      description: post.excerpt.rendered.replace(/<[^>]*>/g, ''),
      images: [post._embedded?.['wp:featuredmedia']?.[0]?.source_url],
    },
  };
}

Imágenes Optimizadas

Usa el componente <Image> de Next.js con dominios remotos configurados en next.config.js:

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

Sitemap y RSS Dinámicos

Genera un sitemap.xml que refleje todos los posts de WordPress:

// src/app/sitemap.ts
import { getPosts } from '@/lib/api';

export default async function sitemap() {
  const posts = await getPosts();
  const postUrls = posts.map((post: any) => ({
    url: `https://tudominio.com/posts/${post.slug}`,
    lastModified: new Date(post.modified),
    priority: 0.8,
  }));

  return [
    { url: 'https://tudominio.com', priority: 1.0 },
    ...postUrls,
  ];
}

Despliegue y Consideraciones Finales

Despliegue del Frontend

La plataforma ideal para Next.js es Vercel (creada por los mismos desarrolladores). Conecta tu repositorio de GitHub y configura las variables de entorno:

  • NEXT_PUBLIC_WORDPRESS_API_URL: https://api.tudominio.com/wp-json
  • REVALIDATION_SECRET: Una cadena aleatoria segura.

Despliegue del Backend

WordPress puede vivir en cualquier hosting compartido o VPS. Sin embargo, para un rendimiento óptimo, considera:

  • Alojamiento administrado: Kinsta, WP Engine o Cloudways ofrecen stacks optimizados para headless.
  • Contenedores: Docker + Nginx + PHP-FPM para un control total.
  • CDN: Coloca Cloudflare delante de WordPress para cachear las respuestas de la API REST.

Pruebas de Carga y Monitorización

Usa herramientas como Lighthouse, GTmetrix y WebPageTest para verificar que tu implementación headless cumple con los estándares. Espera puntuaciones superiores a 95 en rendimiento.

Conclusión

Implementar Headless WordPress con Next.js en 2025 no solo es viable, sino que es la estrategia más inteligente para proyectos que buscan lo mejor de ambos mundos: la facilidad de gestión de contenido de WordPress y la potencia de renderizado de Next.js.

Hemos recorrido desde la configuración de la WordPress API REST, pasando por la creación de páginas estáticas y dinámicas con ISR, hasta la revalidación en tiempo real y la optimización SEO. Esta arquitectura headless, dentro del marco JAMstack, te permite escalar tu proyecto sin preocuparte por la infraestructura tradicional.

[TIP FINAL] No subestimes la importancia de un buen plan de caché y revalidación. Un sitio headless mal configurado puede ser más lento que uno tradicional. Invierte tiempo en entender las estrategias de ISR y revalidación on-demand.

El futuro del desarrollo web es modular, y esta combinación es, sin duda, una de las más potentes y flexibles que puedes dominar. ¡Es hora de construir!

¿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