Traditional WordPress themes can be engineered to perform close to static sites or headless apps. Most WordPress sites already use well-tuned caching and dependency optimizations, yet headless setups still deliver faster loads and smoother transitions. Their drawback is maintenance. A middle path — "nearly headless" — keeps the plugin ecosystem while gaining app-like behavior.

Three rendering models

A traditional WordPress site renders HTML in PHP: every link click triggers a new server request and PHP builds the page. It is the simplest model to maintain, offers the broadest plugin compatibility, and with server-side caching performs reasonably well. Its downside is experiential — transitions and modern effects are harder to build — and JavaScript logic is harder to maintain without a framework. Such sites also tend to be slower than headless variants.

A headless site renders through JavaScript plus a server-side RESTful service such as the WordPress REST API or GraphQL. The server sends minimal HTML and a large JavaScript bundle that handles any page, which yields fast loads and rich page transitions. The cost: significant changes usually require a developer — a forms plugin, an SEO plugin, or a custom block all mean editing the app. Plugins must be re-invented, maintenance is difficult, and hosting is complex and potentially expensive.

The intermediate approach, nearly headless, pairs a small JavaScript app for routing and rendering with a fallback that loads the exact same page through a normal WordPress request. Which pages use the fallback can be chosen through logic injected in either JavaScript or PHP. On a LifterLMS course site, for example, the checkout cart loads via the fallback rather than being rebuilt inside the app, so it behaves exactly as the plugin intends.

Trade-offs

  • Nearly headless pros: easy to maintain once set up; hosting is as simple as a typical theme; pages feel as modern and fast as a headless build.
  • Nearly headless cons: two rendering methods must always be considered; few JavaScript libraries work well with the method; tight coupling to WordPress makes third-party REST APIs harder to integrate than in a fully headless setup.

What the approach requires

A nearly headless setup must load pages via WordPress requests and via JavaScript, keep both renderings identical, know when to choose each path, and guarantee 100% parity on all routed pages. This enables progressive enhancement: a trusted bot can receive the non-JavaScript version for compatibility, and a misbehaving checkout page can be forced onto the fallback until it is fixed.

The open-source library Nicholas implements these requirements and includes a pre-made boilerplate theme.

Single-source markup

Parity between the PHP and JavaScript renderings is the core constraint. Maintaining markup in two places was not acceptable, so the markup needed one source — which immediately ruled out most JavaScript libraries, React included. After research and experimentation, AlpineJS was chosen because it keeps the code reasonably DRY. Some pieces, such as loops, must be re-written per renderer; most substantial markup chunks can be reused.

The same post template in PHP:

<?php
if ( have_posts() ) {
  while ( have_posts() ) {
    the_post();
    if ( is_singular() ) {
      echo nicholas()->templates()->get_template( 'index', 'post', [
        'content' => Nicholas::get_buffer( 'the_content' ),
        'title'   => Nicholas::get_buffer( 'the_title' ),
      ] );
    }
  }
}
?>

And in JavaScript with Alpine:

<template x-for="(post, index) in $store.posts" :key="index">
  <?= nicholas()->templates()->get_template( 'index', 'post' ) ?>
</template>

Both share the same PHP template, so code inside the loop stays DRY:

$title   = $template->get_param( 'title', '' );

// Get the title that was passed into this template, fallback to empty string.
$content = $template->get_param( 'content', '' ); // Get the cotent passed into this template, fallback to empty string.

?>
<article x-data="theme.Post(index)">
  <!-- This will use the alpine directive to render the title, or if it's in compatibility mode PHP will fill in the title directly -->
  <h1 x-html="title"><?= $title ?></h1>
  <!-- This will use the Alpine directive to render the post content, or if it's in compatibility mode, PHP will fill in the content directly -->
  <div class="content" x-html="content"><?= $content ?></div>
</article>