Example Headless WordPress setup, powered by Gutenberg. Forked from Postlight's Headless WordPress + React starter kit.
GPL-2.0 License
This is a fork of Postlight's Headless WordPress toolkit which includes support for Gutenberg. You can read all about it in this handy introduction.
Allow-Origin
headers, and useful logging functions for easy debugging.Let's get started.
Before you get started, make sure you have the following tools set up and added to your PATH
environment variable.
Node.js is the JavaScript runtime we use in the frontend. Download and install it from this link.
Alternatively, if you're on a macOS or Linux system, you can also install Node.js through your operating system's package manager.
The easiest way to install PHP on macOS + Linux is through a package manager (e.g. Homebrew for macOS). This will automatically install PHP on your machine and add it to your PATH
environment variable.
For Windows, the recommended way to install PHP is through XAMPP This is an all-in-one PHP development environment which includes PHP, Apache, and MySQL out of the box. After installing, make sure that the PHP executable is added to your system's PATH
.
The easiest way to install MySQL on macOS + Linux is through a package manager (e.g. Homebrew for macOS). This will automatically install MySQL on your machine and add it to your PATH
environment variable.
For Windows, if you've installed XAMPP as in the previous guide, you should already have MySQL installed! Don't forget to add the MySQL executable to your system's PATH
.
Once you have installed PHP and added it to your PATH
, we can now install Composer, which is a package manager for PHP. We'll use it to install the PHP tools we use.
Follow the installation guides for your specific operating system, and make sure that Composer is properly installed by running:
$ composer
WP-CLI is WordPress' official CLI tool. Install it via composer:
$ composer global require wp-cli/wp-cli-bundle
Make sure that WP-CLI is properly installed by running:
$ wp help
Robo is a configurable task runner. Think Gulp, but for PHP.
Install it via composer:
$ composer global require consolidation/robo
Make sure that Robo is properly installed by running:
$ robo -h
Before setting up, make a copy of the robo-sample.yml
file, and name it robo.yml
. This will contain your WordPress setup configurations.
To set up your new WordPress instance properly configured for headless development, run the following command.
$ robo wordpress:setup
Once finished, we can now run the WordPress server.
$ robo server
nedstark
/ winteriscoming
)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. The primary theme code is located in wordpress/wp-content/themes/postlight-headless-wp
. As you modify the theme code, be sure to use WordPress coding standards.
To spin up the frontend client app, run the following commands:
$ cd frontend
$ yarn
$ yarn dev
The Next.js app will be running on http://localhost:3000.
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:
frontend/config.js
, replace localhost:8080
with your publicly-accessible WordPress installation's domain name or IP address.$ yarn deploy
ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)
If you receive this error, it likely means another version of MySQL, not the version that was installed by this script, is being referenced by the MySQL command.
Open up your .bash_profile
, and see if there is a reference to MySQL in your PATH or if MySQL is being exported as a function. Remove it.
Repeat the installation process. If you still have errors, then look for - and remove - other versions of MySQL by following these "Remove MySQL" instructions.
See anything else you'd like to add here? Please send a pull request!
Made with by Postlight. Happy coding!