WordPress Headless con Astro: Rendimiento Máximo sin Perder la Potencia de Tu CMS

WordPress alimenta más del 40% de la web mundial gracias a su amigable panel de administración y su maduro ecosistema de contenidos. Sin embargo, cuando se trata de velocidad de carga pura, seguridad y flexibilidad en el diseño de la interfaz, la arquitectura tradicional basada en plantillas PHP puede quedarse corta frente a las exigencias modernas de rendimiento y SEO.

Aquí es donde entra el concepto de WordPress Headless (o Desacoplado) en combinación con Astro, uno de los frameworks frontend más veloces de la actualidad. Al separar la gestión de contenidos (backend) de la capa de presentación (frontend), obtienes lo mejor de dos mundos: la interfaz familiar que los redactores aman y una experiencia web ultrarrápida compilada en HTML estático.

En este artículo aprenderás exactamente cómo funciona esta arquitectura, por qué está transformando el desarrollo web moderno y cómo implementarla paso a paso.

Requisitos Previos

Antes de comenzar la integración, asegúrate de contar con lo siguiente:

• Node.js instalado en tu sistema (versión 18.0 o superior).

• Una instalación activa de WordPress (servidor local como LocalWP/Docker o un servidor remoto).

• Conocimientos básicos de JavaScript / TypeScript y manejo de la terminal.

¿Cómo funciona WordPress Headless?

En un sitio monolítico tradicional, el servidor procesa archivos PHP y realiza consultas a la base de datos MySQL cada vez que un usuario solicita una página. En la arquitectura desacoplada, WordPress opera únicamente como un administrador de contenidos (CMS) que expone sus datos a través de una API estructurada (REST API o WPGraphQL).

Estructura de comunicación entre WordPress Headless y el Frontend. Fuente: Kinsta

El frontend desarrollado en Astro consume esos datos mediante peticiones HTTP durante la etapa de construcción (build time) o en tiempo de ejecución (SSR), generando páginas web ligeras con cero JavaScript por defecto enviado al navegador del cliente.

¿Por qué elegir Astro para el Frontend?

Astro destaca por su innovadora Arquitectura de Islas (Islands Architecture). Genera HTML puro por defecto e hidrata componentes interactivos (React, Vue, Svelte) únicamente cuando es estrictamente necesario. Esto se traduce de forma natural en puntuaciones de 100 en Google Lighthouse con un esfuerzo mínimo de optimización.

Paso a Paso: Integrando WordPress Headless con Astro

Paso 1: Habilitar la API en WordPress (WPGraphQL)

Aunque la REST API viene integrada de forma nativa en WordPress, utilizar WPGraphQL suele ser la opción predilecta. GraphQL te permite solicitar únicamente los campos exactos que necesitas, reduciendo drásticamente el tamaño de las respuestas.

1. Ingresa al panel de administración de tu WordPress (/wp-admin).

2. Ve a Plugins > Añadir nuevo.

3. Busca e instala el plugin WPGraphQL.

4. Actívalo. Tu endpoint GraphQL quedará disponible en [https://tu-sitio-wordpress.com/graphql](https://tu-sitio-wordpress.com/graphql).

Paso 2: Crear el Proyecto en Astro

Abre tu terminal y ejecuta el comando de inicialización oficial de Astro:

npm create astro@latest

Sigue las instrucciones del asistente interactivo:

• Asigna un nombre al directorio (ej. astro-wordpress).

• Selecciona una plantilla base (recomendado: Empty o Blog).

• Habilita TypeScript para contar con autocompletado y tipado seguro.

Luego, entra al directorio creado e inicia el servidor de desarrollo local:

cd astro-wordpress
npm run dev

Paso 3: Consumir las Entradas de WordPress desde Astro

Abre el archivo src/pages/index.astro. Vamos a realizar una consulta GraphQL a WordPress para obtener los títulos, extractos y enlaces de las publicaciones recientes:

---
// src/pages/index.astro

// Definición de la consulta GraphQL para obtener los posts
const query = `
  query GetPosts {
    posts {
      nodes {
        id
        title
        slug
        excerpt
        date
      }
    }
  }
`;

// Petición HTTP al endpoint de WPGraphQL
const response = await fetch('https://tu-sitio-wordpress.com/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query }),
});

const { data } = await response.json();
const posts = data.posts.nodes;
---

<html lang="es">
  <head>
    <meta charset="utf-8" />
    <title>Blog con Astro y Headless WordPress</title>
  </head>
  <body>
    <h1>Últimas Publicaciones</h1>
    <section>
      {posts.map((post: any) => (
        <article>
          <h2>{post.title}</h2>
          <div set:html={post.excerpt} />
          <a href={`/blog/${post.slug}`}>Leer artículo</a>
        </article>
      ))}
    </section>
  </body>
</html>

Explicación del código:

El bloque delimitado por --- en la parte superior es el Frontmatter de Astro. Todo este código se ejecuta únicamente en el servidor en tiempo de compilación. Utilizamos fetch para realizar la petición GraphQL y la directiva set:html de Astro para renderizar de forma segura el HTML que devuelve la API en el extracto.

Paso 4: Generar Páginas Dinámicas para los Artículos

Para crear la vista individual de cada entrada (/blog/mi-articulo), se utiliza la funcionalidad de enrutamiento dinámico de Astro. Crea el archivo src/pages/blog/[slug].astro:

---
// src/pages/blog/[slug].astro

export async function getStaticPaths() {
  const query = `
    query GetAllSlugs {
      posts {
        nodes {
          slug
        }
      }
    }
  `;

  const response = await fetch('https://tu-sitio-wordpress.com/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query }),
  });

  const { data } = await response.json();

  return data.posts.nodes.map((post: { slug: string }) => ({
    params: { slug: post.slug },
  }));
}

const { slug } = Astro.params;

// Consulta GraphQL para obtener el contenido específico según el slug
const postQuery = `
  query GetPostBySlug($id: ID!) {
    post(id: $id, idType: SLUG) {
      title
      content
      date
    }
  }
`;

const postResponse = await fetch('https://tu-sitio-wordpress.com/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: postQuery,
    variables: { id: slug },
  }),
});

const { data: postData } = await postResponse.json();
const post = postData.post;
---

<html lang="es">
  <head>
    <meta charset="utf-8" />
    <title>{post.title}</title>
  </head>
  <body>
    <main>
      <h1>{post.title}</h1>
      <p>Publicado el: {new Date(post.date).toLocaleDateString('es-ES')}</p>
      <div set:html={post.content} />
    </main>
  </body>
</html>

Explicación del código:

La función getStaticPaths() le indica a Astro qué páginas dinámicas debe premontar durante la compilación. Astro obtiene la lista completa de slugs de WordPress y compila un archivo HTML estático independiente para cada post, garantizando respuestas instantáneas desde cualquier CDN.

Conclusión y Siguientes Pasos

Adoptar WordPress Headless con Astro desata el verdadero potencial de tu plataforma. Eliminas el sobrepeso de plugins pesados y temas sobrecargados en la capa visual, garantizando páginas ultrarrápidas, mayor seguridad (al ocultar la IP y los archivos sensibles de WordPress) y métricas Core Web Vitals insuperables.

¿Has probado conectar WordPress con frameworks estáticos como Astro o Next.js? ¿Qué plugin usas para gestionar campos personalizados (Advanced Custom Fields o Meta Box) en tus proyectos?