Headless WordPress is all about uncoupling the backend to build a custom frontend. This means you can use WordPress’s content management system (CMS) alongside a powerful framework such as React or Vue. As such, you get to leverage what WordPress and other technologies are best at.
In this post, I’ll discuss how to create a headless WordPress setup, and try to keep my advice “framework-agnostic” as much as possible.
📚 Here’s what I’ll cover:
- What a headless CMS is
- Why you should use WordPress as part of your headless setup
- The technical requirements to set up a headless WordPress site
- How to install and configure WordPress in your headless setup
- Why running headless WordPress as a static site could benefit you
- How to secure your headless WordPress site
Introducing the headless CMS concept 🤗
“Headless” tech has been around for a while, and goes through cycles of popularity. When it comes to a headless CMS in particular, it means decoupling two things:
- The backend content management functionality.
- The frontend presentation layer.
In this instance, the head is the frontend. A headless CMS gives you the greatest flexibility and freedom to create as you see fit. Of course, given that the WordPress CMS is number one for many, you could argue that the backend is the real head here!
Even so, decoupling the WordPress backend can help to extend what’s possible with the platform – and others. You get to experiment with, scale, and further integrate other tech into your projects.
For end users (e.g., the site’s writing/marketing team), they can continue to use the WordPress CMS as they always have done. As the site owner, you get greater frontend development scope. As an example, you can integrate React, or bring your knowledge of Vue.js to the platform. This may even boost collaboration between you and other design teams.
On a technical level, headless WordPress can deliver better performance and enhanced security. This is again down the versatile way you can tailor solutions to specific project requirements. Let’s look a little more at some of these plus points next.
The benefits of using WordPress as a headless CMS 👌🏻
Headless WordPress is more than only flexible: it’s performant and scalable too. However, the flexibility is a standout feature for using it.
For instance, you can build almost any frontend system on top of WordPress’s robust backend. This may be using a JavaScript framework you have skill with, or a static site generator such as Gatsby.
This makes WordPress more adaptable, with fewer limitations as a whole. It also serves as a kind of “future-proofing”, as you will be able to change up the frontend as technology develops.
This adaptability and flexibility extends to performance too. With a headless WordPress setup, you can optimize both sides of the coin as much as you need. What’s more, the whole system is less resource-intensive. This is because it doesn’t need to manage both content and presentation at once.
The swift loading times and high-class performance will also make your setup more scalable. Again, you have an independent structure of front and backend that can both scale without reliance on the other.
All in all, a headless WordPress setup can ensure a top user experience (UX) and the greatest capacity. This is regardless of the traffic levels and content volume of your site.
The technical prerequisites for setting up a headless WordPress ⚙️
Despite the positives, a headless WordPress setup isn’t quick or easy to put in place. You’ll need several prerequisites, both technical and personal:
- Your server will still need to run a typical LAMP stack to accommodate the backend tech.
- On top of this, you’ll need to ensure your server supports both PHP and Node.js at the same time. Node is your runtime environment that makes the whole setup work.
- Of course, you’ll need to choose a frontend framework, and that will be a subjective decision. You should consider your knowledge, goals, and resources to find the right framework.
- As such, your technical knowledge has to extend beyond WordPress into whatever other tools and tech you’ll use too.
To touch on this last point a little more, it’s natural you’ll need to know your framework inside and out. You also have to understand the relationship between WordPress, your framework, Node.js, and your server technology. If any of these need dependencies, this will increase your bedside reading time.
For instance, the WordPress REST API is also key to the setup process. This helps transfer content between WordPress and your frontend tech. Often, you’ll also use JavaScript libraries such as Axios to make HTTP requests too.
You may even need to use some third-party WordPress plugins to set up extra content fields. For example, Advanced Custom Fields is the go-to solution here. You might even decide to generate GraphQL schema for your requests, which is faster than the WordPress REST API. WPGraphQL is ideal for this:
In short, there’s a lot you’ll need to know, but once you’re ready, you can begin to set up a headless WordPress site.
How to set up headless WordPress in four steps 👩🏽🏭
Setting up WordPress as a headless CMS requires a strategic approach. In general, you’ll need coding skills to create the most flexible solution. Later on, we’ll discuss how there are other options to consider, with less versatility.
1. Install and configure WordPress for headless use
Building a headless WordPress site starts as every other setup does: with a fresh installation of WordPress. If you run a server already, it’s simple to spin up a new site within your host’s admin panel.
However, you can set up a local site first too. This could either use an app such as Local or DevKinsta, or a manual MAMP or WAMP installation.
Your site should be typical, in that it runs as a “coupled” WordPress install.
When it comes to a theme, it’s best to choose a blank one so it doesn’t take up resources. Your site’s actual visitors will never interact with this WordPress theme because you’ll be building the frontend separately.
The final part of this initial setup is to activate and verify the WordPress REST API. Headless WordPress needs to use JSON files, so this is a necessary step. It’s simple to do this. Head to the Settings → Permalinks screen in WordPress, choose a pretty permalink structure (Post name is good), and verify access.
For this last task, head to the yoursite.com/wp-json/wp/v2/ URL in your favorite browser. If you see JSON content, everything is running as it should:
Note that you could also fire off a GET request too. Regardless, at this point, you can begin to decouple the frontend of WordPress.
2. Set up your presentation layer application
This part of the process is the most subjective, because it relies on you choosing a framework and implementing it.
There are plenty of frameworks to integrate, although you’ll likely opt for one of a small number:
- React. I like this approach, because you might not need to set up redirects. Setting up the components you need feels straightforward, as is displaying the frontend.
- Vue.js. My personal favorite JavaScript framework is simple to use, and takes arguably less build time than React. It’s a mature framework, yet has less usage for WordPress, thanks to the dominance of React.
- Angular. Despite its steep learning curve, this framework has a higher percentage of users than Vue, which is surprising. Once you know Angular, there shouldn’t be too many issues, though.
Creating the whole frontend app in each of these is beyond the scope of this post. This is where your knowledge and skills will earn its keep. Even so, the setup process should be straightforward to each framework.
In React, it takes three lines of code. Vue, it’s four lines to create the development environment, move into the site folder, and set up npm:
npx create-vite-app my-site
cd my-site
npm install
npm run devIf you want to use third-party dependencies to make HTTP requests, you’d also need to install a library such as Axios here. At this point, we’re moving onto consumption, so let’s discuss that in more detail.
3. Consume the WordPress REST API in your JavaScript framework
In simple terms, you’ll need to fetch your content from WordPress using one of a few methods.
JavaScript offers the native Fetch API to make HTTP requests to the WordPress REST API endpoints. Some like to use Axios because of its backwards compatibility with older browsers. Also, it obfuscates some processes, such as automatic JSON data conversion.
A similar consideration is whether you use the REST API or integrate GraphQL:
- GraphQL. This gives you more granular control over retrieving data. You can specify the exact fields and nested relationships you need, and merge multiple queries into a single API call. It also lets you define custom queries and types, which is often handy.
- REST API. This is familiar and uses simple HTTP methods (
GET,POST,PUT,DELETE) to retrieve queries.
If you want to use GraphQL, WordPress has a solution for you. You’re able to use the WPGraphQL plugin to expose a GraphQL endpoint for WordPress if you wish:
My advice, though, is to not sweat it if you’re new to creating a headless WordPress site. Stick with the REST API, given that it’s already within WordPress and is easy to use.
In contrast, GraphQL is modern, has greater efficiency, and the helper plugin does some of the heavy lifting for you.
4. Display your app on the frontend
The final step to set up a headless WordPress website is to render the frontend. Again, depending on your choice of framework, you’ll have a different process here.
The basic premise is to loop through a dedicated posts component, fetching endpoints for the various elements of the page. This will be data such as the title of the post, an excerpt, or featured image.
You should also consider using a router with your framework. In simple terms, this is how you fetch, display, and navigate between your pages on the frontend – or “mapping different routes.” React Router is specific to its namesake framework, as is Vue Router.
From here, you can build and deploy your site however you want. Many choose to deploy a static website for ease of use. Let’s discuss this more next.
Setting up a static headless WordPress site ⚡️
WordPress by default is a dynamic platform. Although static sites have more drawbacks, they’re ideal in lots of situations where you don’t need constant site updates.
Headless WordPress and static sites go hand-in-hand, and there are lots of static site generators available. For instance, Gatsby is a popular framework for React and GraphQL users:
You’ll still need to know React, and building a Gatsby site takes just as much work as a manual approach. Still, the documentation is excellent and you can build sites fast.
For an alternative, consider a solution such as AWS. This could be the answer if you want to create a static, headless WordPress site fast and low cost.
As a final approach, keep an eye on the WordPress Interactivity API. This is essentially the Frontity framework, but within the WordPress ecosystem. It’s dynamic, but acts much like a static site generator. It could be ideal if you use React and want the benefits of static sites while keeping yours dynamic.
How to secure a headless WordPress setup 🔐
Security is of even greater importance for headless WordPress, as now you have two systems to maintain. As such, you need to be hyper-vigilant to protect your front and backends.
Your typical WordPress measures will always work here. Regular updates, backups, and using security plugins are all necessary considerations. You’ll know to use encrypted connections for your site too.
However, there are specific security considerations you can make for headless WordPress sites. For example, the WordPress REST API includes functionality to help verify connections. You can add a check statement to the rest_authentication_errors filter that requires authentication for all requests. This way, only authorized and verified entities can access and manipulate data.
You can also fine-tune user access to REST API endpoints using a callback. You’ll need to register the permission_callback, which will return an error if it can’t authenticate the user.
Speaking of which, your resource-restrictive security polices could cause a Cross-Origin Resource Sharing (CORS) error. To resolve this, it’s typical to configure the server to specify which “origins” can access resources. You can also use a plugin for this, such as Enable CORS:
While a plugin gives you a streamlined solution to CORS issues, hard-coding this can be the best approach most of the time.
Conclusion 🎬
Uncoupling the frontend of your site can open up a whole world of capabilities. Your backend will still run on WordPress’s stellar CMS functionality. However, your frontend can use almost any framework or technology you like. React gets lots of support, while Vue is straightforward and capable.
You might also consider a static site generator, as they can offer performance benefits in some cases. Gatsby is popular for this purpose, while WordPress will soon have its own implementation. The native Interactivity API could give everyone access to static, headless WordPress sites in the future.
Do you still have any questions about setting up your own headless WordPress project? Let us know in the comments section below!
