Headless WordPress with Atlas
Headless WordPress is a specific setup where WordPress itself no longer generates the pages on the front-end of your website. Instead, WordPress functions only as the back-end for content creation and the WordPress API. Any other platform that can connect to the WordPress API can then be used to set up a website. This means no more plugins or themes, and a completely decoupled front-end from the website’s data sources.
Headless has become popular for a number of reasons:
- Developer Choice – Developers want to use modern frameworks like React to build sites and applications, and headless enables that possibility.
- Scalability – When you remove the burden of rendering from WordPress, you reduce the load on your WordPress instance which allows WordPress to scale much easier with greater traffic.
- Security – Removing the responsibility of rendering from WordPress reduces the surface area for attacks. Now, you can choose to only expose the API to the internet.
- Integrations – It is true that the WordPress community provides many integrations through plugins, but they don’t always work well together. When you go headless, you have more control over your integrations, and most services support integrating with JavaScript and Node.js.
About Headless
When we talk about headless with WordPress, we mean that we are using WordPress for content creation but not for front-end rendering. Instead of using traditional WordPress themes, you develop your front-end using a JavaScript framework like React. In addition, the front-end is hosted on a separate server than the WordPress instance.
Since the front-end is responsible for displaying content to the end-user, it needs to access the content. In order to do that, it utilizes the WordPress REST API or GraphQL via WPGraphQL. These tools allow a different front-end from the standard WordPress to be loaded, typically a NodeJS framework like Next.js or Gatsby.
Utilizing APIs, especially in a headless environment, affords site owners the ability to aggregate data from many sources without having to set up reverse proxies or other confusing configurations. Additionally, this improves performance and security by decoupling the pieces needed to run a website and allowing only the WordPress API to be exposed.
NOTE: If you need a refresher on what an API is, we suggest looking over the WordPress Codex API guide.
Headless and WP Engine
WordPress runs on PHP, but it’s likely that your headless site will utilize Node. At the very least, you’ll use Node and NPM to manage JavaScript dependencies and bundle your applications (i.e. webpack).
At WP Engine, we now offer an enterprise-grade Node hosting platform called Atlas. This platform works differently than our typical WordPress platform. With WordPress, you get a server that you can SFTP or SSH into, but with Node, the infrastructure is opaque to you. All you need to do is point our platform to a GitHub repo, and we’ll watch the repo and deploy it automatically!
Our Atlas headless framework plugin has been designed to lock down the front-end, provide a way to live-preview your headless site from within the wp-admin using the regular “Preview” options, and automatically serve optimized images.
Headless WP Engine Concepts
The Node hosting platform, Atlas, is part of the solution for a headless site. The other part is the WordPress instance itself. These 2 work together to make up your website.
We call the Node portion of your site an app. An app can have any number of environments.
Apps and Environments
An app is a logical container of all of your environments for the Node portion of your site. An app can have multiple environments like Production, Staging, and Development.
Apps are linked to a single GitHub repository (EX: https://github.com/matt-landers/headless-wpe) while environments are linked to a branch within the repository of the app.
It’s up to you to decide which branch relates to which environment. It’s common for your main branch to be linked to your Production environment.
Here’s an example configuration for a typical app with a Production and Development environment:
{
"name": "MyHeadlessApp",
"repo": "matt-landers/headless-wpe",
"region": "US-C",
"environments": [
{
"name": "Production",
"branch": "main",
"wp_environment_name": "headlesswpe",
"domains": ["yourdomain.com"],
"env_variables": [
{ "key": "WORDPRESS_URL", "value": "https://headlesswpe.wpestaging.qa" }
]
},
{
"name": "Development",
"branch": "dev",
"wp_environment_name": "headlesswpe-dev",
"env_variables": [
{ "key": "WORDPRESS_URL", "value": "https://headlesswpe-dev.wpestaging.qa" }
]
}
]
}
The app has 3 properties:
- name – the name of your app which you choose.
- repo – the GitHub repository linked to your app.
- region – the region where you want your app hosted (this setting cannot be modified)
- EU-W – Europe West
- UK – United Kingdom
- US-C – US Central
- AUS-SE – Australia Southeast
- environments – an array of environments that your app contains.
- Each environment is deployed to the platform and receives a unique URL.
Each environment has the following properties:
- name – the name you choose for the environment.
- branch – a branch that exists in the GitHub repo linked to the app.
- wp_environment_name – the name of the WordPress environment (found in the user portal) that you want to link to your Node environment.
- env_variables (optional) – an array of environment variables that you want to be available at build-time and runtime as OS environment variables.
- In Node, you can access these variables with process.env.
- Environment variables are useful for storing information needed to build or run your application like API keys/secrets.
- domains – (optional) If you want to connect a custom domain, you need to configure your domain one of 2 ways:
- Root CNAME pointed to
js.wpenginepowered.com - A records with the following IPs:
141.193.213.10141.193.213.11
- Root CNAME pointed to
NOTE: Currently, only one custom domain is supported.
Connecting the WordPress Back-End
Each app environment is paired with a WordPress back-end. In the WP Engine User Portal, the WordPress equivalent to an app is a site. A site has environments just like apps.
Each app environment needs to be paired with a site environment via the site’s environment id (found in User Portal). You make the connection by setting the wp_environment_name property for each environment in your app config.
The wp_environment_name property is required as it provides the authorization context for the environment which determines which users have access to modify and deploy the app environment.
Getting Started
If you would like to build on WP Engine’s Atlas framework, please reach out to your Account Manager or our Sales team for pricing and further details.
NOTE: Atlas is not available for accounts hosting on AWS.
Once your account has been enabled for use with Atlas, you will see the following “Headless apps” menu in the User Portal. This is where you will create and manage your headless apps on WP Engine.
Additionally, you will need the following requirements:
To learn more about how to get started, see the WP Engine Developers guide at: https://developers.wpestaging.qa/
Troubleshooting
If you are experiencing issues with your app deploying, we recommend the following guide: http://developers.wpestaging.qa/docs/headless/guides/troubleshooting
A headless website can combine many external and custom coded elements. Be aware that WP Engine is not able to assist with debugging custom or third-party code.
