Planning for Headless WordPress and Atlas

Francis Agulto Avatar


In this article, I will discuss the topics and concepts that you will need to understand when considering and planning for Atlas as your Headless WordPress platform. Additionally, as you think about workflows, CI/CD, developer team structure, and developing on Atlas as a whole, I will go over several strategies and considerations that can help guide you.

If you have not yet tested or developed on Atlas, please access a free developer sandbox account here.

If you are new to Headless WordPress or Atlas, please reference these guides: Atlas, Headless WordPress Roadmap

Building a website in Headless WordPress

The approach of building a Headless WordPress website is different from traditional WordPress in that Headless does not require that the requested data be created and then sent to the server to be processed. Rather, the data is pre-compiled and is made available to the browser through the Content Delivery Network, or CDN for short.

This rendering begins with your modern JavaScript framework of choice pre-building your files (JavaScript, HTML, etc). It is important that the framework chosen supports static site generation, regardless of which rendering pattern you use. Once the files are generated, you can deploy them on the CDN. 

What this does is it removes the need for the browser to go through a long and time-consuming series of interactions between the server, database, and cache, improving the performance and speed of the website.

In a traditional monolithic workflow, you have a developer writing code and programming the site. Then they ship it to the server where the server does the work of producing the HTML requested by the client and shipping that to the client. This is done upon every client-side request.

One key decision in the planning of a Headless WordPress site is which files the developer chooses to generate at runtime versus generating them at build time. The decision to generate your files at build time or server-side rendering them at runtime may depend on several factors – how much content can be delivered statically, requirements for dynamic content (dynamic pages or smaller dynamic components, and performance needs).

There is the flexibility of using different rendering patterns in Headless WordPress with your choice of a JavaScript framework, however, the foundation of the Jamstack or decoupled methodology is to pre-render as much content as possible during build time.

Workflow Steps in using Atlas

Here are the major line items you and your teams must decide when approaching a plan to build Headless WordPress on Atlas:

  1. Choose a front-end JS framework like Faust.js, Next.js, Vue, etc. Oftentimes this may be based on what you and your team are familiar with. Also consider some of the features of WordPress that the Publishers may require (post previews, sitemaps) and ensure the framework supports these.
  2. Choose your WordPress API whether that is WP REST or WPGraphQL. Both can be used and if you need help deciding, please reference this article. If you have a preexisting WP install and want to migrate the data you can easily do so with the migration plugin via WP Engine.
  3. Ensure your front-end code is in GitHub and is integrated with Atlas.
  4. Create any Markdown files necessary on your front end and render the data to the files. This is outside any dynamic content to be rendered at runtime.
  5. Lastly, push changes in GitHub and deploy to Atlas.

Atlas Abstract: What it provides

When you adopt Headless WordPress and choose Atlas, you not only get the Atlas platform, an ecosystem of defined tooling such as a CDN and infrastructure, but Atlas also supplies a lot of moving parts in the abstract. These layers that are abstracted allow developers to have a seamless workflow and experience without having to use multiple vendors, systems, etc. Let’s get into details on what Atlas provides and things you should consider.

Continuous Integration/Continous Deployment

One of the most difficult things you can do as a developer is to set up a build system and CI/CD pipeline. There is a lot of toil in this workflow that most developers do not want to do. This is why the emergence of services-hosted platforms, such as Atlas, has taken their place in the market. Fully managed, taking care of this all for you.

The Atlas platform has a simple one-click connection to your Github making it painless to integrate with your repository.

Other services (such as AWS) may allow you to select your own deployment zone, however, with Atlas, the CDN and the target are baked in. You are provided with everything you need to build and host your Headless site.

Atlas’s build environment gives you a secure and customizable build step.  When you build your app on Atlas, it will set up your environment and server, grab any needed dependencies, run the build and deploy.  It supports all tooling, front-end frameworks, site generators, etc involved in building your site.  You can customize your node and yarn versions, install dependencies, create custom build and start commands as well as trigger a build with webhooks from the WordPress backend should your content editors need it.

Atlas CDN

A content delivery network (CDN) is a group of servers that are distributed geographically and work together to provide fast and speedy delivery of internet content. Your assets such as your HTML pages, JavaScript files, stylesheets, images, and videos are quickly transferred onto a CDN for optimal access and performance to your users.

A properly configured CDN may also help protect websites against some common malicious attacks, such as Distributed Denial of Service (DDOS) attacks.

A CDN can’t replace the need for proper web hosting, but it does help cache content at the network edge, which improves website performance. Adding it to your website hosting helps optimize for performance.

The CDN is a layer in your web tech stack that you must account for when you are in the planning phases of adopting Headless WordPress. Doing this ad-hoc and DIY can be time-consuming and tedious for the developer team.  In order to alleviate this issue, Atlas does this for you out of the box.

Atlas’s out-of-the-box CDN utilizes caching to reduce hosting bandwidth, helping to prevent interruptions in service, and improving security, and performance. A CDN, by nature, is distributed geographically which reduces the time it takes to get to your users. When you combine this with the approach of the Jamstack/decoupled architecture which prebuilds the markup, all those files become available statically on the CDN.

In summary, the Atlas CDN provides:

  • Improving website load times
  • Reduced bandwidth costs
  • Increased content availability and redundancy
  • Improved security

WordPress APIs and 3rd Party APIs

The next thing to consider in planning for the development of Headless WordPress is the WordPress install itself. Questions arise such as where to host it, which API you will use (WPGraphQL or REST), plugins, pairing environments with the JS frontend, and any customization to it.

Even though a static Jamstack site can indeed be nothing more than a collection of static assets, connecting your application to your WP backend with the WPGraphQL or REST API is what shows the true power and promise of this as an architecture for real-world applications.

This is the power and foundation behind the modular, decoupled, Jamstack approach. It gives frontend teams the power to not have to write any backend code. They can consume the WordPress data through an API endpoint, mainly REST or GraphQL.

In fact, you’ll find many traditional players like Shopify, SalesForce, BigCommerce, GitHub, etc now offer APIs so they, too, can be consumed in a headless fashion. The explosion of APIs speaks to the momentum of the decoupled movement as the architecture of the interconnected web. As this API-driven development is becoming the norm, Atlas will support it.

Once you decide what API you will use for WordPress, you will need a WordPress host for that install. On Atlas, you have a trusted WP hosting platform fully managed.  You can rest assured that your WP install is kept secure, up to date, and given best-in-class maximum uptime as well as provisioning new WP installs with a simple click.

FAQs/Best Practices 🌐 🤓

Q: Can the size of a developer team affect the decisions on the kind of workflow implemented in Headless WordPress? (Large Agency/Small Independent Contractor)

A: This is a subjective question because the size and number of a dev team are relative. However, for this article’s sake, let’s just say there can be a single one-person developer, a small dev team is about 2-5, and anything above 5 is mid to large.

The main thing to consider here is your environments as far as development, staging, and production. If you have a large developer team that is pushing numerous changes to your code, it is a necessity to ensure those changes are exactly what you wanted before going live. Isolating these changes in environments solves this.

A single developer can set up a simplified workflow with maybe only one or two environments, plus local. The Local Sites tool is great for a single developer workflow.

When a development team is small to large, there are three things to consider when planning a workflow – 1) Everyone is able to contribute, 2) Everyone has access to the most recent versions, and 3) All developers are able to iterate through CI/CD.

For larger agency teams, especially when developers are switching between projects, you might want to use a containerized approach where you can create a repeatable/cloned environment that each team member can use.

Q: What if I want an efficient way to check my code on the browser without pushing it to production?

Deployment previews in Atlas allow you to deploy a preview environment on a live URL without having to procure any isolated staging environment. It gives you a unique live site that is isolated off any feature branch you checkout. This will alleviate the issue of spinning up multiple staging environments and make your Atlas workflow better.

Q: What are some recommendations for making sure your front & backend deploy at the same time?

A: There are different ways you can approach the answer to this. For example, if you need to push changes to the WordPress backend to add and or remove functionality, and push changes to the frontend app synchronously to accommodate those backend changes, what is the best way to do so? 🤔

Two main solutions that are most commonly used are:

  1. Push changes for the frontend & backend at the same time and don’t worry about the time variance. This would work for hobby sites, but not important ones where a page in an error state could mean an abandoned shopping cart, etc.
  2. Include fallback code and do it in stages. Push code to the frontend and backend that tries to use the new changes, but gracefully falls back to the old version if it’s not available. This approach could use a feature flag, check for a certain version number, etc. Then once you’re confident all users are on the new version of the frontend application, push another update to finally remove the old functionality.

One thing to note is that there really is no perfect solution to this question or any solution in Headless web development for that matter. The challenge of keeping your different code bases in sync from a timing perspective in this approach will have trade-offs on any option you choose and these are things that come with the territory. The key here is to just figure out which trade-offs mean more to you and your team. 

If you want a more granular example of these solutions to this question, we will have a deeper dive into it in an article to come soon!

Let us know your thoughts!

Feedback is golden on a product for developers. If there are any features that you want to see on Atlas and WordPress as a Headless CMS, please let us know! Drop us a line in our discord channel. Stoked!!! 🎉