Alex Standiford, a WordPress developer at AffiliateWP, has released a boilerplate for what he is calling a “nearly headless” WordPress theme. It uses Underpin ,Nicholas, and AlpineJS to provide an app-like experience for a website while providing the flexibility for rendering specific pages using PHP instead of Javascript.

In a post titled “Headless WordPress is Overrated: A Case for The Nearly-Headless Web App,” Standiford describes a few of the drawbacks of going fully headless.

One problem with fully-headless WordPress is routing. Behind the scenes, WordPress has a lot of logic built-in to handle routing, and with a headless approach you have to build something to handle that on the front end. Ultimately, you’re re-inventing the wheel, and it takes a lot of extra time to build.

Another problem with headless WordPress quickly becomes apparent the moment you try to use most WordPress plugins. The ugly truth is that you usually have to re-invent a lot of things just to get the plugin working properly. 

Standiford’s nearly headless system is a product of his rethinking headless WordPress. He wanted to preserve the app-like feel as well as all of WordPress’ built in capabilities and those available through the plugin system.

The Nearly Headless WordPress theme uses AlpineJS for rendering, which Standiford says is light, easy-to-understand, and “plays exceptionally nice with PHP server-side rendering.” It is loaded around HTML template tags that source post content using WordPress’ REST API. The system uses session storage to keep things speedy and minimize the number of REST API calls.

Standiford’s WP Dev Academy learning site and his agency, DesignFrame Solutions, are both using beta versions of the nearly headless system. Since the time those sites were developed, Standiford has completely rewritten the system and made significant improvements based on what from what he learned from earlier versions. He has a live demo of the current version available at nearly-headless.dev.

The nearly headless approach is comparable to a traditional headless approach in terms of performance, thanks to Standiford’s Nicholas library, which includes client-side caching and a routing layer as the application support for the theme.

“Nicholas will load content via REST, much like how a headless site does,” Standiford said. “In these cases, the load times are very similar to what you’d see on a headless site. In fact, they behave, and fundamentally work in the same manner. The key is Nicholas also stores the data in session storage after the page is visited, and any time that page is loaded thereafter, it is loaded instantly.”

How far can the boilerplate take you? Developers who use it should be ready to extend or replace the basic templates it includes to load WordPress. It doesn’t enqueue any CSS. Key functionality is broken into separate dependencies so users can stay up to date as the project evolves.

“For all intents and purposes, the boilerplate is a blank slate,” Standiford said. “You can think of the boilerplate as _s for the nearly headless approach. All of the dependencies, scripts, and items needed to run the engine are included in the boilerplate. All of the dependencies are packaged up in Composer or Node, so your theme can be updated as the system improves without re-writing your entire theme.”

Standiford has some major improvements planned for the future of the boilerplate. It is currently compatible with the block editor and many plugins but requires a compatibility mode.

“The big up-front improvement is going to be removing the need for compatibility mode on as many pages as possible,” Standiford said. “Many block libraries, forms plugins, and other things have specific scripts that they expect are loaded on the page that the app has no way to know about, and because of this, some plugins won’t work without turning on compatibility mode. It is possible to make these work, but I would benefit from help from plugin developers to help me understand what styles/scripts need to be included when the app runs.”

Standiford said he sees an opportunity to create npm packages that integrate other plugins, and ensure they work as expected.

“Yoast and other SEO plugins for example set the SEO information in the head of each page, and right now that doesn’t happen without writing another piece of middleware,” he said. “It’s not too difficult to add it, but it’s one of those things that could be packaged up and included instead of manually being written for every theme that uses this approach.”

Another item on the Nearly Headless WordPress theme boilerplate roadmap is improvements to how dependencies are compiled to better avoid plugin and theme conflicts. Standiford thinks this would make it easier to distribute themes built using this method on the WordPress.org directory, or even to sell them commercially. He has also been experimenting with automatically caching all the content on a page when it loads, without bogging down the browser or overloading the server with requests. The result would be instantaneous page loads with reduced server loads.

The Boilerplate for Nearly Headless WordPress Themes is available on GitHub and Standiford is also creating a course that will help developers build sites using this nearly headless paradigm. He anticipates it will be released in November 2021.