Cancel

Sarah Gooding

New Boilerplate Speeds Up Building “Nearly Headless” WordPress Themes

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.

https://twitter.com/AlexStandiford/status/1336468966160683017

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.

Category: ,
Tags:
11

11 responses to “New Boilerplate Speeds Up Building “Nearly Headless” WordPress Themes”

    • Some questions: How are the REST API implicit limits handled? Like if there are more items than max. number of returned items in one call? Are X-WP-Total, X-WP-TotalPages etc. headers taken care of? Are data of several subsequent necessary REST API calls combined in session storage? How is expiry of data handled, e.g. if new content is available but not yet in session storage?

      Create forum topic from comment

      • Are X-WP-Total, X-WP-TotalPages etc. headers taken care of?

        Nope. Not yet. The request doesn’t use a traditional REST call, it creates a different endpoint that fetches data that is otherwise not easy to obtain in the context of REST. Check out This directory.

        Are data of several subsequent necessary REST API calls combined in session storage?

        Yep. Session storage stores the data from the REST calls in session storage, and then the entire system actually loads the data from session storage instead of the API call. The app itself determines what local URLs need to be cached, and only requests the URLs it does not already have.

        How is expiry of data handled, e.g. if new content is available but not yet in session storage?

        I’m so glad you asked this question!

        A piece of session storage data is set for the last time the cache was cleared, and there is a piece of middleware that will validate the cache every 5 minutes. If the date of the cleared cache does not match, all of the session storage data is wiped.

        The cache is cleared every time a post type is updated, or if you manually clear the cache in the settings.

        Create forum topic from comment

  3. This is a cool initiative. I’ve been looking into headless for the better part of this year, mostly with Atlas from WP Engine. But so far I haven’t rolled out any ‘real’ projects with it.

    The statements in the article about having to reinvent the wheel are totally true. Having a contact form with something like Gravity Forms is an absolute drag. Figuring out routing is difficult.

    I’d have liked it more if this boilerplate would’ve used GraphQL instead of the Rest API. It’s so much nicer to work with when things get more complex! The biggest downside to GraphQL is that most plugins have no built-in support for it yet, although the community it quickly spewing out extensions to add that support.

    Create forum topic from comment

    • I would love to use GraphQL instead of REST, and it’s not impossible to move it over to use that, it would just take some effort.

      All of the REST endpoints are baked-in here: https://github.com/nicholas-wordpress/underpin-module

      Since the boilerplate does not include these files directly, it’s possible to create a GraphQL version that could be swapped out instead of the RESTful version if it were to be built.

      I think an SDK for the actual REST calls would be useful too, since you could then make it so that the function calls from the SDK dynamically choose if it’s using GraphQL or REST to help keep compatibility in the core functionality, but then you could extend it to do whatever you need it to-do on your own.

      Create forum topic from comment

  6. Seems interesting! For the past couple of months I was thinking about such an eco-system that acts like headless but offers the freedom of using majority of WordPress plugins and does not require an additional nodejs server to run for the decoupled front-end.

    End users aren’t heavily tech-savvy so making the process as smooth and simple as possible should be the ultimate goal. Like the process should be the same to install and activate a theme that they’re used to.

    I’ll surely spend some time with this boilerplate.

    Great job ! Keep up the pace.

    Create forum topic from comment

  7. We’re using similar partial headless approach for our commercial theme WPLMS. The core WP architecture comes with inbuilt Redux store creation which makes it really easy to create applications, small which can also talk to each other on the same page. This is an immense opportunity by as it transforms WordPress into an Application framework. We’ve also also released a addon for AffiliateWP plugin which works in same headless framework.

    Create forum topic from comment

You may also like

Newsletter

Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.