WP Engine Headless Concepts

The Node hosting platform is part of the solution for a headless site. The other part is the WordPress instance. These two work together to make up your site.

We call the Node portion of your site an app. An app can have n number of environments. Let's explore these concepts.

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 link to a single GitHub repository (i.e., https://github.com/matt-landers/headless-wpe). Environments link to a branch within the repository of the app. It's up to you to decide which branch relates to which environment. For example, it's common for your main branch to link 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.wpengine.com" }
"name": "Development",
"branch": "dev",
"wp_environment_name": "headlesswpe-dev",
"env_variables": [
"value": "https://headlesswpe-dev.wpengine.com"

The app has four 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 (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 Atlas 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 help store 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. Custom domains require a production environment.
    • Root CNAME pointed to js.wpenginepowered.com
    • A records with the following IPs:

Each app environment pairs with a WordPress backend. In the WP Engine User Portal, the WordPress equivalent to an app is a site. A site has environments just like apps. Therefore, each app environment needs to pair with a _site environment_ via the site's environment id found in the 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.

Atlas CLI gives you access to all the commands needed to spin up your first Headless application. npm is required to install the CLI.

NOTE: With version 0.1.4 released March 18, 2021, Atlas CLI no longer requires the alpha syntax (i.e., wpe alpha apps). If you are still using a previous version of Atlas CLI, run through these steps to use commands without alpha.

To install, enter:

npm i @wpengine/headless-cli -g

Verify the installation:

wpe --version

If the installation was successful, your terminal applications returns:

wpe version vX.X.X

NOTE: If your version is lower than 1.0.0 (e.g. 0.9.9) you need to upgrade your CLI using npm i @wpengine/headless-cli -g command. Support for versions lower than 1.0.0 will stop on 09/30/2021.

You'll now be able to follow the other guides and tutorials on this site, as well as use any command in the CLI reference.