1

WHITE PAPER Headless WordPress on WP Engine

HEADLESS WORDPRESS ON WP ENGINEWHITE PAPER

2

WHITE PAPER Headless WordPress on WP Engine

IntroductionHeadless WordPress is a hot topic around the WordPress community. But “Headless” can mean many things, depending on who you ask. So before we cover how Headless WordPress works on WP Engine, we’ll start by defining some core concepts.

Headless and Brainless WordPress Terminology“Headless” WordPress: In short, Headless WordPress simply means “No WordPress front-end.” Companies who use an entirely Headless solution will typically host a separate JavaScript application for the front-end, which pulls specific WordPress data via the REST API. The data the app pulls can include: user data, page and post data, categories, products, and more. That means your app can have a static index.html file hosted in your site’s root directory or hosted within a separate directory. Or, it can mean your JavaScript app is hosted elsewhere. For example, the “front-end” of a mobile app is hosted on each device that downloads it.

“Brainless” WordPress: Using WordPress functionality and the REST API in tandem. While Headless “consumes” data from WordPress, Brainless actually uses WordPress when building the front-end. Brainless implementations use WordPress to compile minimal HTML and static assets upon the initial page request. It then allows JavaScript to construct the entirety of the front-end while consuming data from the REST API.

REST API: When we speak of the WordPress REST API, we’re talking about getting and updating JSON (JavaScript Object

Notation) listings of your site’s data stored in the database via calls to the /wp-json/ path on your website. For example, if I go to mywebsite.com/wp-json/v2/posts/, here’s what I get:

If I make a GET request to this page with curl, I should get this same data back too. Here’s an example of the same type of request I just made in my web browser:

And using this data, I can use JavaScript and styles to display it in a way I want - in a feed, in a slider, and so on. It doesn’t stop with just posts and pages. You can use the REST API for user data and user management, WooCommerce products and order listings, Jetpack data, comments, Custom Post Types, the list goes on. While /wp-json/ is the default path used for the REST API, this can be customized to a different path as well.

JavaScript Framework: Choosing a JavaScript framework can be difficult simply because of the sheer number of options available for Headless and Brainless implementations. Some of the heavy hitters include: Vue, React, and Angular (all of which use Node.js for their build process). For the purposes of this article, we will focus on building a Headless or Brainless WordPress site using the Angular framework.

3

WHITE PAPER Headless WordPress on WP Engine

Benefits of Headless and Brainless WordPressHeadless and Brainless implementations of WordPress offer some key benefits for sites:

Flexibility: Once you have a Headless or Brainless implementation, you can very easily construct another app, service, or even another website that hooks into your site’s REST API data as well.

Scalability: Particularly with fully Headless WordPress, all of the work to build your page is offloaded to your user’s web browser (or their device in the case of a mobile app) with JavaScript. That means your site is fast and your server can handle a LOT more concurrent traffic, since it’s only passing static assets to the user. With Brainless WordPress, the initial page construction does take place on the server, but the rest is handled browser-side. So even still, your server doesn’t have the stress of building as many pages concurrently as with standard WordPress.

Bundling: Modern JavaScript Frameworks implement technologies such as WebPack to bundle static assets (.js and .css). The fewer assets your user’s web browsers has to load, means your site is super lightweight and fast.

Brainless WordPress Example: SkyPress on WAR FrameworkNow that you know what Brainless WordPress is, let’s look at a use-case example of a Brainless configuration. The SkyPress site uses its own framework, called WAR: WordPress, Angular, REST API. This framework allows you to create proper data models and WordPress endpoints via the WAR API plugin, and consume this data using the WAR Parent theme.

Let’s take a look at the war-api plugin first. This WordPress plugin (PHP code) creates full CRUD API endpoints based on your own unique data models. The plugin also defines how the data is fetched with GET requests. You can use the standard WP REST API path

(/wp-json/) or define your own prefix instead (/api/ for example). The plugin will also allow authorized WordPress users to authenticate either with the standard WordPress auth cookie, or using JavaScript Web Tokens (JWT).

Now that your API endpoints and data models are defined in the war-api plugin, the war-angular theme helps build the front-end. The functions.php file registers the JavaScript libraries needed, and enqueues the static assets (JavaScript and CSS).

Here’s what the end result looks like in the JavaScript console on a first-load of the page:

We can see the styles, images, and HTML files being loaded in addition to the /api/ path (the custom prefix inserted instead of /wp-json/).

Now on a new page, the static assets aren’t reloaded at all. The only items loaded are directly related to the REST API call.

ConsiderationsIf you’re thinking about creating a Headless or Brainless WordPress site, there are some things you should consider first:

Does your site require authentication? If so, whether you choose to go Headless or Brainless matters a lot. For a truly Headless solution, users would have to authenticate in your JavaScript app, and then authenticate again for WordPress actions and data. That means

4

WHITE PAPER Headless WordPress on WP Engine

passing authentication headers from your JavaScript application front-end back to WordPress with each request. If you’re using the Brainless method, because WordPress is actually compiling that page initially you’re able to use the same authentication for the application and WordPress itself with the use of X-WP-Nonce headers.

Are you prepared for local development? With both Headless and Brainless WordPress configurations, you need to develop your application, bundle, and build locally. Then your build can be deployed to the server where your WordPress site is hosted, into the index.html file (in the root of your Headless app) or index.php file (in the root of your Brainless theme or plugin). This development workflow ties in neatly to Continuous Integration and Continuous Deployment tools like Codeship and Deploybot.

Where should your front-end application live? For a fully Headless solution, the front end can be hosted on the same server architecture as your WordPress site. But depending on the type of application you’re building, you may discover that the front-end is or needs to be separately hosted. For example, with a mobile app, the “host” for your JavaScript application front-end is each end-user’s mobile device. The only actions happening on the server where your WordPress site is hosted would be the REST API calls to gather data.

Headless and Brainless WordPress on WP EngineWhen developing a Headless or Brainless website on WP Engine you should use the following workflow:On your local machine (Angular in this example):

1. Install your JavaScript framework’s CLI tools.

2. Develop your TypeScript files (object programming/classes, typecasting) and HTML templates.

3. Bundle/Transpile and Minify your TypeScript files into a single bundle.min.js file using your framework’s CLI tools.

4. Test your Build

5. Deploy to WordPress (Git, Deploybot, Continuous Deployment tools)

On your WP Engine site:Only a finished product should live in your production WP Engine site. All development should be managed locally and deployed to WP Engine. Scope of Support:WP Engine is a WordPress Digital Experience Platform. That means WP Engine Support can help you with the WordPress aspects of your site like:

• Troubleshooting REST API issues• Help with standard WordPress functionality

WP Engine Support can also help with questions about platform features such as:

• Caching, CDN, Backups, SSL, and other WP Engine-managed components

• Troubleshooting Deploy issues

WP Engine Support cannot help with:

• Code conflicts on your JavaScript front-end• Troubleshooting JavaScript errors• Overriding default WordPress functionality• Development issues or concerns• Bundling questions or concerns

About WP EngineWP Engine powers amazing digital experiences for websites andapplications built on WordPress. The company’s premium managed hostingplatform provides the performance, reliability and security required by thebiggest brands in the world, while remaining affordable and intuitiveenough for smaller businesses and individuals. Companies of all sizes relyon WP Engine’s award-winning customer service team to quickly solvetechnical problems and create a world-class customer experience. Foundedin 2010, WP Engine is headquartered in Austin, Texas and has offices in Limerick, Ireland, San Francisco, California, San Antonio, Texas, and London, England. www.wpengine.com

6

WHITE PAPER Headless WordPress on WP Engine

wpengine.cominfo@wpengine.comWP Engine 504 Lavaca Street, Suite 1000, Austin, Texas 78701