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

Implementación de arquitectura headless con WordPress y Astro

Actualizado el 14 de febrero de 2026

La evolución del desarrollo web ha llevado a muchos equipos a replantearse la relación entre el backend de gestión de contenidos y el frontend de presentación. Durante años, WordPress ha sido el rey del monolitismo: un mismo servidor servía el panel de administración, la base de datos y el tema que renderizaba el HTML. Sin embargo, la llegada de arquitecturas desacopladas ha cambiado las reglas del juego. Combinar WordPress headless con Astro no solo es técnicamente viable, sino que ofrece un rendimiento, una seguridad y una flexibilidad que los temas tradicionales difícilmente pueden igualar.

En este artículo, exploraremos en profundidad cómo implementar una arquitectura headless utilizando WordPress como backend de contenidos y Astro como generador de sitios estáticos (SSG) o servidor en tiempo real. Veremos desde la configuración inicial hasta las estrategias de SEO headless, pasando por la gestión de rutas y la optimización de imágenes.

¿Por qué WordPress headless con Astro?

Antes de sumergirnos en el código, conviene entender por qué esta combinación es tan potente.

Ventajas de un CMS headless con WordPress

WordPress, como CMS headless, deja de encargarse de la capa de presentación. Esto significa:

  • Mayor seguridad: Al no exponer el panel de administración ni los temas al público, se reduce drásticamente la superficie de ataque.
  • Rendimiento puro: El frontend se construye con tecnologías modernas (React, Vue, Svelte o, en nuestro caso, Astro) que optimizan la entrega de recursos.
  • Reutilización de contenido: El mismo WordPress puede servir datos a una web, una app móvil y un panel IoT, todo desde la misma API REST o GraphQL.

Por qué Astro es el compañero ideal

Astro no es un framework de componentes cualquiera. Es un generador de sitios estáticos que, por defecto, envía cero JavaScript al cliente. Esto encaja perfectamente con un CMS headless porque:

  • Renderizado híbrido: Puedes generar páginas estáticas, dinámicas o incluso islas de interactividad.
  • Cero JS por defecto: Ideal para sitios que priorizan velocidad y SEO headless.
  • Integración nativa con APIs: Astro consume cualquier fuente de datos, desde REST hasta GraphQL.

[INFO] Astro no reemplaza a WordPress; lo complementa. WordPress sigue siendo el mejor CMS para gestionar contenido editorial complejo, mientras Astro se encarga de servirlo con la máxima eficiencia.

Configuración del backend: WordPress como API

El primer paso es preparar WordPress para que funcione exclusivamente como backend. No necesitas un tema tradicional; de hecho, es mejor desactivar cualquier tema que renderice HTML.

Instalación y plugins esenciales

  1. Instala WordPress en un servidor o localmente (puede ser un subdominio o una instalación aparte).
  2. Desactiva todos los temas y activa un tema mínimo como Twenty Twenty-Four (lo usaremos solo como placeholder).
  3. Instala los siguientes plugins:
    • WPGraphQL (recomendado sobre REST para consultas más eficientes).
    • Advanced Custom Fields (ACF) con su extensión WPGraphQL para campos personalizados.
    • Yoast SEO o Rank Math (la metadata se expondrá vía API).
    • WP Rocket o Redis para caché (opcional, pero mejora la respuesta de la API).

Configuración de la API REST

Si prefieres REST sobre GraphQL, asegúrate de que los endpoints estén activos. Ve a Ajustes > Enlaces permanentes y elige una estructura que no sea la simple (por ejemplo, /post-name). Luego, verifica que /wp-json/wp/v2/posts devuelva JSON.

# Ejemplo de consulta REST básica
curl https://tudominio.com/wp-json/wp/v2/posts?_fields=id,title,slug,excerpt

Para GraphQL, tras instalar WPGraphQL, el endpoint será /graphql. Puedes usar herramientas como GraphiQL para explorar el esquema.

Exponer campos personalizados

Imagina que tienes un campo ACF llamado meta_descripcion. Para que aparezca en la API, debes mapearlo con WPGraphQL:

// functions.php del tema (o un plugin personalizado)
add_action('graphql_register_types', function() {
    register_graphql_field('Post', 'metaDescripcion', [
        'type' => 'String',
        'description' => 'Descripción personalizada del post',
        'resolve' => function($post) {
            return get_field('meta_descripcion', $post->ID);
        }
    ]);
});

[TIP] No expongas toda la base de datos. Limita los campos que realmente necesita Astro para mantener la API ligera y segura.

Construyendo el frontend con Astro

Ahora pasamos a la parte divertida: crear un proyecto Astro que consuma WordPress.

Inicialización del proyecto

# Crea un nuevo proyecto Astro
npm create astro@latest mi-proyecto-headless
cd mi-proyecto-headless
npm install @astrojs/node @astrojs/vercel # o el adaptador que prefieras

Configuración de variables de entorno

Crea un archivo .env en la raíz:

WORDPRESS_API_URL=https://tudominio.com/graphql
WORDPRESS_REST_URL=https://tudominio.com/wp-json/wp/v2

Luego, en astro.config.mjs:

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'hybrid', // o 'static' si todo es pregenerado
  adapter: node(),
  site: 'https://tudominio.com',
  vite: {
    define: {
      'process.env.WORDPRESS_API_URL': JSON.stringify(process.env.WORDPRESS_API_URL),
    }
  }
});

Consumiendo la API de WordPress

Crea una carpeta src/lib/ y dentro un archivo wordpress.js:

export async function fetchPosts() {
  const query = `
    query Posts {
      posts(first: 20) {
        nodes {
          id
          title
          slug
          excerpt
          featuredImage {
            node {
              sourceUrl
              altText
            }
          }
          metaDescripcion
        }
      }
    }
  `;

  const response = await fetch(process.env.WORDPRESS_API_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query })
  });

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

Página principal con listado de posts

En src/pages/index.astro:

---
import Layout from '../layouts/Layout.astro';
import { fetchPosts } from '../lib/wordpress';

const posts = await fetchPosts();
---

<Layout title="Inicio - Mi Blog Headless">
  <h1>Últimos artículos</h1>
  <ul>
    {posts.map(post => (
      <li>
        <a href={`/blog/${post.slug}`}>
          {post.featuredImage && (
            
          )}
          <h2>{post.title}</h2>
          <div set:html={post.excerpt} />
        </a>
      </li>
    ))}
  </ul>
</Layout>

Página de detalle dinámica

Crea src/pages/blog/[slug].astro:

---
import Layout from '../../layouts/Layout.astro';
import { fetchPostBySlug } from '../../lib/wordpress';

export async function getStaticPaths() {
  const posts = await fetchPosts();
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post }
  }));
}

const { post } = Astro.props;
const content = post.content; // HTML limpio de WordPress
---

<Layout title={post.title}>
  <article>
    <h1>{post.title}</h1>
    <div set:html={content} />
  </article>
</Layout>

[WARNING] El contenido HTML de WordPress puede incluir estilos inline o scripts no deseados. Siempre sanitiza el HTML con DOMPurify o similar antes de inyectarlo.

Estrategias de SEO headless

Uno de los mitos más comunes es que WordPress headless perjudica el SEO. Nada más lejos de la realidad. Con Astro, puedes controlar cada aspecto técnico del SEO.

Metadatos y Open Graph

Astro permite inyectar etiquetas <meta> directamente en el <head>. Crea un componente SEO.astro:

---
export interface Props {
  title: string;
  description: string;
  image?: string;
  url: string;
}

const { title, description, image, url } = Astro.props;
---

<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>{title}</title>
<meta name="description" content={description} />
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
{image && <meta property="og:image" content={image} />}
<meta property="og:url" content={url} />
<meta name="twitter:card" content="summary_large_image" />

Luego, en cada página, pasa los datos desde WordPress:

<SEO 
  title={post.title}
  description={post.metaDescripcion || post.excerpt}
  image={post.featuredImage?.node.sourceUrl}
  url={`https://tudominio.com/blog/${post.slug}`}
/>

Sitemap dinámico

Astro puede generar un sitemap.xml de forma nativa. Instala el integrador:

npm install @astrojs/sitemap

Y en astro.config.mjs:

import sitemap from '@astrojs/sitemap';

export default defineConfig({
  integrations: [sitemap()],
  site: 'https://tudominio.com'
});

El sitemap se generará automáticamente con todas las rutas estáticas. Para incluir rutas dinámicas (como posts individuales), asegúrate de que getStaticPaths devuelva todas las URLs.

Velocidad de carga y Core Web Vitals

Astro ya optimiza imágenes y elimina JS muerto, pero puedes ir más allá:

  • Imágenes responsive: Usa @astrojs/image para generar múltiples tamaños desde las URLs de WordPress.
  • Caché de API: Implementa un caché con node-fetch-cache o un CDN como Cloudflare para evitar consultas repetitivas a WordPress.
  • Precarga de enlaces: Con @astrojs/prefetch puedes cargar páginas en segundo plano cuando el usuario pasa el ratón.

Despliegue y mantenimiento

Opciones de hosting para Astro

Astro es agnóstico en cuanto a despliegue. Puedes usar:

  • Vercel (recomendado por su integración nativa con SSR y Edge Functions).
  • Netlify (ideal para sitios estáticos puros).
  • Un servidor Node.js (con el adaptador @astrojs/node).

Actualización de contenido en tiempo real

Si tu sitio es estático (SSG), cada vez que publiques un nuevo post en WordPress deberás regenerar el sitio. Puedes automatizarlo con webhooks:

  1. En WordPress, instala un plugin como WP Webhooks.
  2. Configura un endpoint que llame a tu servicio de despliegue (por ejemplo, un hook de Vercel).
  3. Cada vez que se publique o actualice un post, el webhook disparará una nueva build de Astro.

Para sitios híbridos o SSR, Astro puede consultar la API en cada petición, pero entonces perderás parte de la velocidad estática.

[INFO] Si necesitas contenido en tiempo real sin perder rendimiento, considera usar Incremental Static Regeneration (ISR) en Vercel o un CDN con purga selectiva de caché.

Conclusión: ¿Merece la pena la arquitectura headless?

La combinación de WordPress headless con Astro no es una moda pasajera. Resuelve problemas reales: seguridad, velocidad y escalabilidad. A cambio, exige un cambio de mentalidad: ya no arrastras un tema pesado, sino que construyes un frontend a medida, con herramientas modernas y sin ataduras.

Si tu proyecto necesita un CMS potente pero quieres ofrecer una experiencia de usuario impecable, esta arquitectura headless es, sin duda, una de las mejores decisiones que puedes tomar. El SEO headless no solo es posible, sino que puede superar al de los temas tradicionales si aplicas las buenas prácticas que hemos visto.

Ahora es tu turno. Abre tu terminal, instala WordPress, lanza Astro y empieza a construir el futuro de tu web.

¿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