Skip to content


Switch branches/tags
This branch is 200 commits ahead, 151 commits behind postlight:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
  Headless Wordpress Site is build using Postlight's Wordpress starter.

Dev Setup

WordPress Backend

Before you install WordPress, make sure you have Docker installed. On Linux, you might need to install docker-compose separately.


The following commands will get WordPress running on your machine using Docker, along with the WordPress plugins you'll need to create and serve custom data via the WP REST API.

> docker-compose up -d
  • Attach to the wp-headless container.
> docker exec -it wp-headless /bin/bash
  • Setup headless wordpress by running yarn
> yarn install

When the installation process completes successfully:

Run React Frontend

To spin up the frontend client app, run the following commands:

> docker exec -it wp-headless /bin/bash
> cd frontend && yarn install && yarn start

The Next.js app will be running on http://localhost:3000.

Import Data (Optional)

To import data and media from a live WordPress installation, you can use the Migrate DB Pro plugin, which is already installed. To do so, in the robo.yml file, set the plugin license and source install. Run robo wordpress:setup, then run robo wordpress:import to pull in the data.

Update Plugins / Core (Optional)

  • Attach to the wp-headless container and use the WP CLI:
> docker exec -it wp-headless /bin/bash
> wp plugin update --allow-root
> wp core update --allow-root

Note: new plugins which affect the rest APIs will need to be added to the api-accelerator plugin in mu-plugins.


Install the google cloud cli and login.

To deploy the node frontend:

gcloud beta app deploy frontend/app.yaml --no-cache

To deploy the wordpress backend, add a wp-config.php file with database creds to wordpress, and run:

gcloud app deploy wordpress/app.yaml

Postlight Headless WordPress + React Starter Kit Info

Postlight's Headless WordPress + React Starter Kit is an automated toolset that will spin up two things:

  1. A WordPress backend that serves its data via the WP REST API and GraphQL (new!).
  2. A server-side rendered React frontend using Next.js.

You can read all about it in this handy introduction.

What's inside:

  • An automated installer script which bootstraps a core WordPress installation that provides an established, stable REST API.
  • A plugin which exposes a newer, in-progress GraphQL API for WordPress.
  • The WordPress plugins you need to set up custom post types and custom fields (Advanced Custom Fields Pro and Custom Post Type UI).
  • Plugins which expose those custom fields and WordPress menus in the WP REST API (ACF to WP API and WP-REST-API V2 Menus).
  • All the starter WordPress theme code and settings headless requires, including pretty permalinks, CORS Allow-Origin headers, and useful logging functions for easy debugging.
  • A mechanism for easily importing data from an existing WordPress installation anywhere on the web using WP Migrate DB Pro and its accompanying plugins (license required).
  • A starter frontend React app powered by Next.js.
  • A Docker container and scripts to manage it, for easily running the frontend React app and backend locally or deploying it to any hosting provider with Docker support.

Extend the REST and GraphQL APIs

At this point you can start setting up custom fields in the WordPress admin, and if necessary, creating custom REST API endpoints in the Postlight Headless WordPress Starter theme. You can also modify and extend the GraphQL API.

The primary theme code is located in wordpress/wp-content/themes/postlight-headless-wp. Remember to lint your code as you go.


Most WordPress hosts don't also host Node applications, so when it's time to go live, you will need to find a hosting service for the frontend.

That's why we've packaged the frontend app in a Docker container, which can be deployed to a hosting provider with Docker support like Amazon Web Services or Google Cloud Platform. For a fast, easier alternative, check out Now.

To run the Docker container locally:

  1. In frontend/config.js, replace localhost:8080 with your publicly-accessible WordPress installation's domain name or IP address.
  2. Start the container by running this command:
> yarn run deploy

Troubleshooting Common Errors

Breaking Change Alert - Docker

If you had the project already setup and then updated to a commit newer than 99b4d7b, you will need to go through the installation process again because the project was migrated to Docker. You will need to also migrate MySQL data to the new MySQL db container.

CORS errors

If you have deployed your WordPress install and are having CORS issues be sure to update /wordpress/wp-content/themes/postlight-headless-wp/inc/frontend-origin.php with your frontend origin URL.

See anything else you'd like to add here? Please send a pull request!

Made with ❀️ by Postlight. Happy coding!


No releases published


No packages published


  • PHP 68.8%
  • CSS 17.8%
  • JavaScript 9.8%
  • SCSS 3.4%
  • Other 0.2%