What Is Headless WordPress (And How Do You Use It)?

Your Headless WordPress roadmap: Getting started

So Headless WordPress is right for your project? Here’s a quick getting started guide to help you out.

Preparing the backend: Plugins and site setup

The first thing you need is a WordPress site.

Tip: WordPress.com’s Business plan or above provides a managed, scalable, and secure WordPress environment for sites of any size.

WordPress.com eliminates many of the infrastructure headaches associated with a self-hosted setup. You have all the features needed for custom WordPress builds, knowing everything behind the scenes is handled. Using WordPress.com, you have a perfect starting point for your Headless build with full access to developer features like GitHub deployments, real-time backups, and SSH.

If you want to just test a few things and follow along with this tutorial, you can also use WordPress.com’s free and open source local development environment, Studio, to spin up a local WordPress installation.

WordPress ships with a REST API, but as mentioned above, many developers opt for the WPGraphQL plugin when building Headless sites, which allows us to add a GraphQL endpoint to your WordPress site. 

If you opt to use the REST API instead, you can start without installing any plugins.

Creating a content structure for API consumption

Let’s consider a WordPress post or page. We have a title, an ID, a slug, a featured image, and a few more fields. However, most posts have rich content added via the editor, which makes up most of the post content.

For this reason, the post content from the block editor may vary significantly between posts.

On the other hand, content like WooCommerce products or a custom post type with custom fields (for example, a post type defined with Secure Custom Fields) may have many more meta fields and little or no content from the block editor.

Why does this matter? The structured meta fields, such as the post title, are easier to handle when pulling content from WordPress. We have a pretty good idea of how it will look and what data we’ll find there.

The block editor content, on the other hand, is a large string of text containing blocks and nested blocks. We have less control over this content and can make fewer assumptions about its shape.

The simple way to handle block content is to set it directly as HTML in a div on the frontend. This will give you the same CSS classes and markup as the WordPress post, and you can style these in your front-end app or import the block styles as part of your build process.

Another approach is to fetch the Gutenberg block markup, recursively parse the content, and map the blocks to corresponding components on your frontend. For example, a Gutenberg block, like an image, can be parsed to an equivalent .tsx or .astro component in your front-end code.

While it gives you more flexibility, it also means you must write a new component for every block you plan to use.

This is also where you should consider what data you need from WordPress. Some use cases may only require fetching posts, while others need menus, SEO data, and user information. 

Contact forms or comment submissions may also need to be returned to WordPress via REST requests unless you plan to handle them differently.

Fetching data

On your WordPress site’s dashboard, head to the WPGraphQL area. You’ll see the GraphQL IDE, which is where you can start interfacing with WordPress via GraphQL. 

Tip: If you’re unfamiliar with GraphQL, check out the WPGraphQL docs.

It’s easy to build complex queries with clauses, pagination handling, and nested data while seeing the output instantly in the admin using the IDE.

Building the frontend

Once we can fetch data from the backend, either via REST or GraphQL, we can start translating this logic to our frontend.

Astro is a good option, and I added some notes on the integration below. 

Due to the variety of sites, use cases, and frameworks, this is by no means a complete tutorial on how to build a WordPress-powered Astro site. Still, the steps are general enough that they will apply to most similar frontend frameworks and give you an idea of how to get started.

You can start a new Astro project by running the following in your terminal:

npm create astro@latest -- --template blog

This will give you the latest version of Astro with prebuilt blog templates. By default, this blog is powered by Astro’s content collections and will render markdown (and MDX) from .md and .mdx files stored in the frontend repository.

In addition, we’ll need a few dependencies for interfacing with WordPress via GraphQL:

npm install graphql-request graphql

Let’s start our project to see what we’re working with by running npm run dev. From the terminal output, we can see that the site runs on localhost:4321.

Our current Astro site renders content from files in the src/pages directory, where the [...slug].astro is dynamic and responsible for parsing and rendering the markdown files inside the src/content/blog directory. 

Since we’ll get our content from WordPress, we can remove the src/content directory and the content.config.ts file.

In src/consts.ts, define a new constant for your site’s WPGraphQL endpoint. Reminder: This can be a live site or a local Studio site.

// 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';

We already know we need to get all posts, the slugs, and a single post given a slug. As we progress, more queries will likely be required. Category, tag, and author pages already come to mind. 

We can create a new file at src/lib/graphql.ts. 

Any query you need can be added and exported from this file. The IDE inside the WPGraphQL admin page is a great place to experiment and write new queries. Let’s add one to fetch all our posts for now:

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
          }
        }
      }
    }
  }
`;

Using the fetched data in our frontend

In Astro, we’re opting for a static build. Because of this, we must tell it which pages to build for us. 

We can modify the [...slug].astro file with getStaticPaths, allowing Astro to know all the possible URLs/paths at build time.

It also allows us to use the data directly in the template:

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 || [];

We can now run npm run build && npm run preview, which will convert all our static paths (e.g., blog posts) into HTML files and serve the static files from a local dev server:

Final thoughts: Going Headless with WordPress

In this post, we’ve covered the pros and cons of Headless WordPress, how to fetch data from our WordPress.com backend, and how you can quickly get started with a new Headless frontend in Astro.

Although my example is a very simple site, WordPress.com offers a robust, low-maintenance backend for Headless sites of any size, whether it is an ecommerce site, an app, or a content-heavy site. 

Our managed infrastructure, security, and API-first capabilities make WordPress.com an excellent choice for businesses and developers looking to scale.