¿Qué es headless WordPress (y cómo se utiliza)?

Headless WordPress es un concepto que está transformando la manera en la que desarrolladores y empresas utilizan WordPress, ya que separa la gestión del contenido del desarrollo del front-end.

En el modo headless, WordPress funciona solamente como gestor de contenido (enviándolo a través de una API), lo que te permite elegir la tecnología front-end que quieras para crear el sitio o la aplicación que se enseña al usuario.

Esto significa que, con el modo headless, tienes la posibilidad de crear un front-end totalmente estático, usar el renderizado del servidor, o bien mezclar ambos métodos. Además, puedes utilizar cualquier framework o biblioteca que busque datos en una API externa, como React, Vue, Astro, Next.js o un generador de sitios estáticos.

También se puede utilizar WordPress en modo headless en webs de e-commerce, aplicaciones SaaS y apps móviles que funcionen con WordPress. Quizá te suene el ejemplo de la aplicación móvil Jetpack.

Pero, ¿cómo puedes saber si a tu proyecto le va bien la configuración headless? ¿Y cómo se hace exactamente? Sigue leyendo:

1. Separado, pero no desconectado: ¿qué es headless WordPress?
2. ¿Para quién es el modo headless WordPress?
3. ¿Hay alguna desventaja a la hora de utilizar el modo headless?
4. Cosas a tener en cuenta antes de elegir el modo headless
5. Hoja de ruta del modo headless en WordPress
6. Conclusiones finales: el modo headless en WordPress

Separado, pero no desconectado: ¿qué es headless WordPress?

Antes de profundizar en el asunto, veamos cómo suele gestionar WordPress una solicitud del usuario:

En un entorno tradicional, WordPress se encarga de todo: la gestión de contenido y la capa de presentación.

A grandes rasgos, una solicitud de un usuario tiene esta pinta:

• Un usuario solicita una página de tu web.
• La solicitud va a WordPress a través de NGINX, donde cargamos el wp-config, ajustes, plugins y el tema activo.
• Se determina la página/entrada solicitada, y se consultan los datos en la base de datos.
• Con una jerarquía de plantillas, se determinan las plantillas específicas (page.php, single.php, etc.).
• La plantilla carga la cabecera, el contenido, el pie de página y las demás secciones necesarias.
• WordPress genera el HTML y lo envía al navegador, donde se renderiza para que el usuario pueda verlo e interactuar con él.

Un sitio headless se parece mucho a un sitio normal. Pero, en un sitio headless, el front-end debe transmitir las solicitudes a la API REST de WordPress (o al endpoint de GraphQL), y es el front-end el que tiene que generar y entregar el HTML.

En un sitio headless, una solicitud funciona de forma parecida a esto:

• Un usuario solicita una página de tu web.
• La aplicación del front-end (p.ej.: Next.js, Astro o cualquier otro framework) transmite la solicitud a WordPress a través de la API REST o del endpoint de GraphQL. Pero esto puede resultar innecesario, ya que es posible que el HTML ya haya sido generado en una build totalmente estática o si la respuesta ya está en la caché.
• La solicitud va a WordPress (de forma similar a una configuración más tradicional).
• WordPress invoca al REST API Router (en REST), o WPGraphQL analizará la consulta.
• Se consulta la base de datos.
• Se genera el JSON y vuelve a la aplicación de front-end, que gestiona los datos de retorno del JSON (p.ej.: actualizar el estado local, volver a renderizar el DOM, etc.).

El modo headless se refiere a cualquier configuración de WordPress en la que WordPress actúa como capa de contenido, mientras que el front-end se genera de forma separada. Hay muchas maneras de hacerlo, y funciona de forma diferente en las distintas aplicaciones.

Algunas aplicaciones de front-end utilizan renderizado desde el servidor (SSR), donde el marcado se genera a través de un nodo del servidor (y se almacena en la caché). Muchos frameworks disponen de adaptadores para hacerlo, como el adaptador Astro de Cloudflare, que se encarga de la lógica del SSR en tu lugar.

Algunos sitios headless son completamente estáticos y utilizan la generación de sitios estáticos (SSG), en la que el back-end de WordPress solo se utiliza para generar los archivos HTML del sitio. Una vez creado el sitio, la API de WordPress ya no se utiliza más hasta que la próxima actualización (cuando publiques una nueva entrada de blog o edites alguna página) provoque una reconfiguración. Esto significa que, cada vez que cambies algo en tu web o en su contenido, el sitio tendrá que ser reconfigurado (total o parcialmente, a través de una SSG parcial).

Si el sitio está activo, todo el HTML y el marcado ya ha sido creado, y los usuarios recibirán esos archivos HTML estáticos.

El método que eligas para configurar el sitio depende del proyecto y de lo que resulte más eficiente para tu caso concreto. Por ejemplo: ¿puedes realizar un renderizado previo de una página antes de que el usuario la solicite? Si es así, el método SSG probablemente te venga mejor.

También es buena idea investigar el hosting donde quieres alojar la aplicación de front-end: revisa su documentación y echa un vistazo a los adaptadores y workflows de los que dispone.

Por ejemplo: WordPress.com ofrece un entorno de WordPress gestionado, escalable y seguro para webs de todos los tamaños. Su infraestructura te puede ahorrar muchos de los dolores de cabeza propios de una configuración de WordPress autoalojada. Tienes a tu disposición todas las funcionalidades que necesitas para crear una web de WordPress personalizada, además de la tranquilidad de que todo está bajo control.

El plan Business es el punto de entrada perfecto para una build headless, ya que tienes acceso a funciones para desarrolladores como los despliegues de GitHub, copias de seguridad en tiempo real y acceso SSH.

¿GraphQL o la API REST del núcleo de WordPress?

WordPress viene con una API REST integrada que es compatible con gran cantidad de plugins de terceros y de la comunidad. La API también se utiliza en el código del núcleo de WordPress y en Gutenberg.

La API REST permite que los usuarios (tanto si han iniciado sesión como si no) puedan realizar operaciones CRUD comunes en páginas, entradas, archivos multimedia y otros elementos según su nivel de acceso.

Puedes elegir si quieres usar la API REST en el código de tu front-end o, si lo prefieres, puedes utilizar el plugin WPGraphQL, con el que podrás realizar las mismas operaciones a través de consultas GraphQL.

Muchos desarrolladores que utilizan sitios de WordPress headless utilizan GraphQL en paralelo a frameworks modernos como Astro, Next.js o Nuxt.

Con GraphQL, podemos solicitar solo los campos que necesitamos y recuperar los datos relacionados a través de consultas anidadas. Por ejemplo: podemos utilizar una consulta para buscar una entrada y su autor con el nombre y la URL de la imagen del avatar.

Una llamada similar a /wp-json/wp/v2/posts?slug=hello-world nos dará muchos más campos. Como se puede ver, mientras que la API REST nos da el ID del autor, no podemos ver la URL del avatar realizando la misma solicitud.

Por otro lado, la API REST de WordPress es compatible desde el inicio: no necesita configuración. Gracias a esto se ha llegado a un ecosistema mucho mayor en el que los plugins proporcionan endpoints a través de la API REST de WordPress (un ejemplo de ello es WooCommerce).

Es muy recomendable que le eches un vistazo a ambas opciones para ver cuál funcionará mejor en tu proyecto.

¿Para quién es el modo headless WordPress?

Normalmente, son las agencias y los desarrolladores quienes más utilizan WordPress en modo headless, sobre todo si buscan tener control total del front-end de un sitio que utiliza el back-end seguro y de confianza de un hosting de WordPress gestionado como WordPress.com.

Otros ejemplos de uso son:

• Empresas y webs con alto nivel de tráfico: el modo headless WordPress va muy bien para organizaciones que necesiten un sistema de gestión del contenido que pueda escalar con su crecimiento sin tener que lidiar con la gestión del servidor.
• Medios de comunicación y plataformas con mucho contenido: una configuración headless de WordPress también puede ser útil para webs que necesiten una entrega de contenido rápida y a través de la API en múltiples canales.
• E-commerce y aplicaciones SaaS: el modo headless puede adaptarse bien a las necesidades de negocios que integran contenido de WordPress en sus tiendas y aplicaciones web o móviles personalizadas.

Puedes adoptar la configuración headless de forma gradual o integrarla en tu sitio de WordPress interactuando con la API REST de WordPress desde tu tema.

¿Hay alguna desventaja a la hora de utilizar el modo headless?

Después de haber leído todo esto, puede parecer que utilizar WordPress en modo headless es siempre la mejor opción. Pero, como todo en la vida, este tipo de configuración tiene sus ventajas y sus inconvenientes.

En muchos proyectos, sobre todo si no eres desarrollador, lo más lógico suele ser confiar en WordPress para todo. Con esta configuración más tradicional, sigues teniendo muchas formas de añadir interactividad gracias al editor de bloques y la API de interactividad. Además, todo funciona bien, porque el propio WordPress ya es una herramienta muy potente.

Pero una configuración headless también implica algunos posibles inconvenientes, como por ejemplo:

• Más mantenimiento: tener dos bases de código y tecnologías distintas para el front y el back-end puede crear una capa de complejidad extra que no te encontrarás en una configuración de WordPress tradicional.
• Gran parte del catálogo de temas, patrones y opciones de diseño de WordPress no estará disponible: tendrás que encargarte por tu cuenta de implementar muchas de estas cosas desde cero, con código. ¿Cómo vas a gestionar los comentarios del blog? ¿Y los formularios de contacto? Todo eso ya viene integrado en el software de WordPress precisamente para facilitarle la vida al usuario final.
• No todos los plugins son compatibles con configuraciones headless: puede que tengas que modificar algunos plugins o exponer sus datos manualmente a la API REST o a GraphQL. 
• Tendrás que gestionar dos entornos de hosting: uno para el back-end de WordPress y otro para el front. En muchos casos, el front-end se puede alojar como archivos estáticos en redes que utilizan tecnologías como GitHub, AWS CloudFront, Cloudflare u otros servicios similares.

Cosas a tener en cuenta antes de elegir el modo headless

¿Todavía no tienes claro si la configuración headless de WordPress es para ti? Ten en cuenta estos aspectos:

• Código y experiencias personalizadas: una configuración headless requiere tiempo de desarrollo y decisiones técnicas adaptadas a tu proyecto. Deberías preguntarte si realmente necesitas la flexibilidad que ofrece esta arquitectura para tu proyecto.
• Familiaridad con la tecnología: ¿estáis tú o tu equipo más acostumbrados a trabajar con PHP, o con JavaScript?
• Los objetivos del proyecto: aunque los sitios headless ofrecen mayor flexibilidad y pueden mejorar el rendimiento (además de ser únicos, desafiantes y divertidos de desarrollar para los programadores), suelen implicar mayor complejidad y más tiempo de desarrollo.
• La tecnología interna de WordPress: al prescindir del sistema tradicional de WordPress, también pierdes características integradas como el almacenamiento en caché o ciertas optimizaciones automáticas. Tendrás que encargarte tú de implementarlas mediante capas de caché o servicios externos.
• Estrategias de caché: con una estrategia bien optimizada que combine servidores de CDN con servicios de caché desde el servidor (como Varnish, NGINX FastCGI cache o un plugin de caché de WordPress), un sitio de WordPress tradicional puede alcanzar niveles de rendimiento similares a los de uno estático.
• WordPress está optimizado para SEO desde el primer momento: con un enfoque headless, tendrás que asegurarte de que el front-end gestiona correctamente el SEO. Esto implica utilizar renderizado desde el servidor (SSR) o generación de sitios estáticos (SSG), algo que ya permiten muchos frameworks de front-end modernos. También tendrás que recuperar los datos SEO desde WordPress (por ejemplo: si una página debe ser indexada, su título SEO, sus metadatos, etc.). Además, tendrás que gestionar las redirecciones por tu cuenta, ya que, con el modo headless, pierdes la gestión de enlaces permanentes que WordPress realiza automáticamente.
• Feeds RSS y mapas del sitio: en una configuración headless, es posible que tengas que implementar estas funciones desde cero en el front-end. En cambio, en WordPress tradicional ya vienen integradas en el núcleo (y en Jetpack si utilizas el hosting de WordPress.com).

Hoja de ruta del modo headless en WordPress

¿Crees que headless WordPress es la opción ideal para tu proyecto? Aquí tienes una guía rápida de todo lo que necesitas para empezar.

Preparar el back-end: configuración del sitio y de los plugins

Lo primero que necesitas es un sitio de WordPress.

Consejo: el plan Business de WordPress.com (o superior) ofrece un entorno de WordPress gestionado, escalable y seguro para sitios de todos los tamaños.

WordPress.com se encarga de muchos de los inconvenientes de la infraestructura asociada a una configuración autoalojada. Tienes a tu disposición todas las funcionalidades que necesitas para una build de WordPress personalizada, pero con la tranquilidad de que todo lo que ocurre entre bambalinas está completamente gestionado. En WordPress.com tienes el punto de partida perfecto para una configuración headless, ya que incluye acceso total a funcionalidades para desarrolladores como los despliegues de GitHub, copias de seguridad en tiempo real y SSH.

Si quieres probar algunas cosas y seguir este tutorial, también puedes utilizar WordPress Studio, el entorno de desarrollo local gratuito de WordPress.com para generar una instalación local de WordPress.

WordPress funciona con la API REST; pero, como hemos mencionado antes, muchos desarrolladores eligen el plugin WPGraphQL a la hora de crear un sitio headless, ya que nos permite añadir un endpoint GraphQL a tu sitio de WordPress.

Si prefieres utilizar la API REST, puedes empezar sin instalar ningún plugin.

Crear una estructura de contenido para su consumo mediante API

Pongamos como ejemplo una página o una entrada de WordPress. Tenemos un título, un ID, un slug, una imagen destacada y algunos campos más. Sin embargo, la mayoría de las entradas incluyen contenido enriquecido añadido con el editor, que además suele ser la mayor parte del contenido.

Por eso, el contenido generado con el editor de bloques puede variar bastante de una entrada a otra.

En cambio, otro tipo de contenido, como los productos de WooCommerce o un tipo de entrada personalizada con campos personalizados (por ejemplo, definido con Secure Custom Fields), puede incluir muchos más campos meta y poco o ningún contenido del editor de bloques.

¿Y por qué es importante esto? Porque los campos meta estructurados, como el título de la entrada, son más fáciles de gestionar al recibir el contenido desde WordPress. Tenemos una idea bastante clara de cómo son y de la estructura de sus datos.

El contenido del editor de bloques, por otro lado, es una gran cadena de texto que contiene bloques y bloques anidados. Tenemos menos control sobre él y no podemos hacer tantas suposiciones sobre su forma.

La manera más sencilla de gestionar ese contenido es insertarlo directamente como HTML dentro de un div en el front-end. Esto te dará las mismas clases CSS y el mismo marcado que tendría la entrada en WordPress, y puedes aplicar estilos en tu aplicación de front-end o importar los estilos de los bloques como parte del proceso de compilación.

Otra opción es obtener el marcado de los bloques de Gutenberg, analizarlo de forma recursiva y mapear cada bloque con su componente correspondiente en el front-end. Por ejemplo, un bloque de imagen de Gutenberg podría convertirse en un componente equivalente .tsx o .astro en el código del front-end.

Esta opción te da mucha más flexibilidad, pero también implica que tendrás que crear un componente nuevo para cada bloque que pienses utilizar.

También deberías plantearte qué datos necesitar recuperar desde WordPress. En algunos casos pueden ser solo entradas, mientras que en otros necesitarás también menús, datos de SEO e información de los usuarios.

También puede que necesites enviar los formularios de contacto y los comentarios a WordPress a través de solicitudes REST, a menos que los quieras gestionar de otra forma.

Obtener los datos

En el escritorio de tu sitio de WordPress, ve a la sección de WPGraphQL. Verás el IDE de GraphQL, desde donde podrás empezar a interactuar con WordPress mediante GraphQL.

Consejo: si no conoces bien GraphQL, échale un vistazo a la documentación de WPGraphQL.

Con el IDE, es muy sencillo crear consultas complejas con cláusulas, paginación y datos anidados, y ver al momento los resultados directamente en el panel de administración.

Crear el front-end

Una vez que podemos recuperar los datos del back-end, ya sea mediante REST o con GraphQL, podemos empezar a traducir su lógica a nuestro front.

Astro es una buena opción, así que hemos preparado una pequeña guía sobre su integración.

Como hay tanta variedad de sitios, usos específicos y frameworks diferentes, estas notas no pretenden ser un tutorial completo para crear un sitio con Astro usando WordPress como base. De todas formas, los pasos son lo suficientemente generales como para que se puedan aplicar a la mayoría de frameworks de front-end similares, y te pueden servir como punto de partida para empezar.

Empieza un nuevo proyecto de Astro introduciendo el siguiente comando en el terminal:

npm create astro@latest -- --template blog

Con esto tendrás la última versión de Astro con plantillas de blog prediseñadas. Por defecto, este blog utiliza las colecciones de contenido de Astro y renderiza el marcado (y el MDX) a partir de archivos .md y .mdx almacenados en el repositorio del front-end.

También necesitaremos algunas dependencias para interactuar con WordPress mediante GraphQL:

npm install graphql-request graphql

Para ver en lo que estamos trabajando, ejecuta npm run dev. Desde el resultado del terminal, podemos ver que el sitio se ejecuta en localhost:4321.

Nuestro sitio de Astro renderiza el contenido de los archivos del directorio src/pages, donde [...slug].astro es dinámico y responsable de analizar y renderizar los archivos de marcado del directorio src/content/blog.

Como vamos a recibir nuestro contenido desde WordPress, podemos eliminar el directorio src/content y el archivo content.config.ts.

En src/consts.ts, define una nueva constante para el endpoint de WPGraphQL de tu sitio. Recuerda: puede ser tanto un sitio activo como un sitio local de WordPress Studio.

// Place any global data in this file.
// You can import this data from anywhere in your site by using the `import` keyword.
 
export const SITE_TITLE = 'Astro Blog';
export const SITE_DESCRIPTION = 'Welcome to my website!';
export  const WORDPRESS_API_URL = 'https://astroheadlessbuild.wpcomstaging.com/graphql';

Ya sabemos que necesitamos conseguir todas las entradas, los slugs y una entrada individual con un slug concreto. Según vayamos avanzando, es probable que haya que realizar más consultas, como categorías, etiquetas y páginas de autores.

Crea un nuevo archivo en src/lib/graphql.ts.

Se puede añadir y exportar cualquier consulta que necesites desde este archivo. Experimenta y escribe nuevas consultas desde el IDE en la página de administración de WPGraphQL. Por ahora, vamos a añadir una para buscar todas nuestras entradas:

import { GraphQLClient } from 'graphql-request';
import { WORDPRESS_API_URL } from '../consts';
 
// Create a GraphQL client instance
export const graphQLClient = new GraphQLClient(WORDPRESS_API_URL);
 
// Query to get a list of posts
export const GET_POSTS = `
  query GetPosts($first: Int, $after: String) {
    posts(first: $first, after: $after) {
      pageInfo {
        hasNextPage
        endCursor
      }
      nodes {
        id
        slug
        title
        date
        excerpt
        featuredImage {
          node {
            sourceUrl
            altText
          }
        }
      }
    }
  }
`;

Utilizar los datos obtenidos en nuestro front-end

En Astro, hemos elegido una build estática. Por ello, tenemos que decirle qué páginas debe crear por nosotros.

Podemos modificar el archivo [...slug].astro con getStaticPaths, lo que permitirá que Astro conozca todas las posibles rutas y URL a la hora de compilar.

También nos permite utilizar los datos directamente en la plantilla.

import { graphQLClient, GET_POSTS } from '../../lib/graphql';
import type { WordPressPostsResponse, WordPressTerm } from '../../lib/types';
import BlogPost from '../../layouts/BlogPost.astro';
import { formatDate } from '../../lib/utils';
 
export async function getStaticPaths() {
  const allPaths = [];
  let afterCursor = null;
  let hasNextPage = true;
 
  while (hasNextPage) {
    const response: WordPressPostsResponse = await graphQLClient.request<WordPressPostsResponse>(GET_POSTS, {
      first: 10, // Fetch in batches of 10
      after: afterCursor,
    });
 
    allPaths.push(
      ...response.posts.nodes.map(post => ({
        params: { slug: post.slug },
        props: { post },
      }))
    );
 
    hasNextPage = response.posts.pageInfo.hasNextPage;
    afterCursor = response.posts.pageInfo.endCursor;
  }
 
  return allPaths; // Return an array as required by Astro
}
 
const { post } = Astro.props;
 
if (!post) {
    return Astro.redirect('/404');
}
 
// Format the post data to match the BlogPost component props
const postData = {
    title: post.title,
    description: post.excerpt.replace(/<[^>]*>/g, ''), // Strip HTML tags
    pubDate: formatDate(post.date),
    updatedDate: formatDate(post.date),
    heroImage: post.featuredImage?.node.sourceUrl || undefined,
};
 
// Get the post content
const content = post.content || '';
 
// Get additional post metadata
const author = post.author?.node;
const categories = post.categories?.nodes || [];
const tags = post.tags?.nodes || [];

Ahora podemos ejecutar npm run build && npm run preview, que convertirá todas nuestras rutas estáticas (como las entradas de blog) en archivos HTML y entregará los archivos estáticos desde un servidor de desarrollo local:

Conclusiones finales: el modo headless en WordPress

En este artículo hemos resumido las ventajas e inconvenientes del modo headless en WordPress, hemos hablado de cómo recuperar datos de nuestro back-end de WordPress.com, y hemos dado unos breves apuntes para empezar a utilizar un front-end headless en Astro.

Aunque este ejemplo es un sitio muy sencillo, WordPress.com ofrece un back-end para sitios headless muy sólido, de bajo mantenimiento y adaptable a sitios de todos los tamaños, tanto para webs de e-commerce como para aplicaciones o sitios con mucho contenido.

Nuestra estructura gestionada, la seguridad y el enfoque en la API hacen de WordPress.com la opción ideal para empresas y desarrolladores que quieran llegar a lo más alto.