Introducing Postlight’s WordPress + React Starter Kit

People who publish on the web love WordPress. Engineers love React. With some research, configuration, and trial and error, you can have both — but we’d like to save you the work.

Meet Postlight’s WordPress + React Starter Kit, a free, zero-to-hero toolkit for engineers and product tinkerers who want to try out headless WordPress on their own computer with minimal effort.

postlight/headless-wp-starter

This starter kit spins up a WordPress backend with a React frontend talking to the WP REST API in two steps. To use it, clone the repository, and check out the README. The first command installs and starts WordPress on your computer, and the second starts a process that serves a React frontend. From there, you’re ready to start importing data from your own WordPress site, and customizing the backend and frontend for your own needs.

Postlight has shipped several headless WordPress projects with a React frontend for our clients in the past year or so, and we got tired of repeating the initial legwork every time. This starter kit automates all the manual steps of setting up headless. We use it internally to start new WordPress projects, and we made it generic enough for you to do the same.

The Business Case: Why Headless WordPress?

In our work with various clients, we’ve seen several scenarios, business reasons, and product requirements that make a WordPress backend with a React frontend make sense:

• Your editorial team knows and loves WordPress, but your product and tech teams want to use modern web development tools and paradigms to build the web site and/or mobile app.
• You want to separate your site’s frontend from the backend to decouple your platform’s main pieces, and make it more resilient and flexible.
• You want your WordPress site’s frontend to be fast and infinitely scalable. (So much depends on your particular configuration, but anecdotally, we saw a significant response time decrease on a client site after transitioning the frontend to React.)
• Your product and engineering teams want to focus on frontend innovations and solving new problems specific to your business, and leverage all the content management solutions WordPress already offers. (Ain’t no shame in it.)
• Your content doesn’t all live in WordPress. Your site or app needs to talk to several APIs, your WordPress content being just one of them, and it’s way easier to do that with a JavaScript frontend.
• You’re ready to migrate your site from WordPress to a new decoupled CMS, but want to do so piecemeal — first the frontend, and then later, the backend.
• You’re building a brand new JavaScript-based site on a tight schedule, and you don’t have the time to build the CMS that powers it from scratch.

Now that the REST API has been in core WordPress for almost a year now, headless WordPress with React works really well in certain situations. But like with any technology solution, there are tradeoffs.

We’ve worked with clients who wanted to move away from WordPress entirely to eliminate PHP and MySQL from their stack, and that is one problem headless WordPress does not solve. You are still running WordPress, and that means you will have to host and maintain it and whatever plugins you are using, and inevitably make some customizations to what the API serves and how it does so. Headless WordPress does require you have some WordPress/PHP skills on your engineering team, but you can isolate that work to backend developers, and free up your frontend talent to work oblivious to WordPress’ inner workings, only aware of how to query the WP API.

The Technical Details: How To Do Headless WordPress?

When you clone Postlight’s WordPress + React Starter Kit, you get the following:

• An installer script which bootstraps a core WordPress installation. Note: This script installs MySQL and WordPress locally; we find virtual machines wonderful in concept but slow and cumbersome to work with in practice.
• The WordPress plugins you need to set up custom post types and custom fields (Advanced Custom Fields Pro and Custom Post Type UI).
• WordPress 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, plus 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. For many WordPress-powered sites, SEO (search engine optimization) is paramount, and some web crawlers (like Google News) can’t parse sites that aren’t plain old HTML. Next.js makes server-side rendering for React easy, so that you’re getting the SEO benefits of a rendered, HTML page as well as the possibilities of client-side React. Note: for smaller-scale sites, static site generators or purely client-side React might meet all your product requirements.
• A frontend app Docker container and scripts to manage it, for easily deploying it to any hosting provider with Docker support (AWS Elastic Beanstalk, Google Cloud, or Now are all great options).

There are many ways to set up and configure headless WordPress, and an infinite number of React libraries and frameworks you can use on the frontend to get your work done. This starter kit represents the groundwork of one way we’ve done it here at Postlight; take this as a suggestion, use what you like, toss out what you don’t, and customize it to your needs.

A Work-in-Progress: Pull Requests Welcome

This starter kit is just getting started — the React side, in particular, is barely a skeleton. We’d love your help fleshing this out. Give it a try, file an issue with your feature request and questions, and send us a pull request with your changes. Most importantly: have fun, and let us know what you think!