Headless WordPress

Headless is a trade: the front end gains a JavaScript framework’s freedom, and the team takes over what the theme layer did for free. It pays off when the same content feeds several front ends (web, mobile, in-store screens), when the front end is an application (heavy client state, an existing React design system, a Next.js team), when WordPress must be isolated on a private network, or when performance targets are easier with a framework’s rendering and image pipeline.

It rarely pays off for a site of pages and posts whose editors rely on front-end plugins, or with no one to own a second application: a block theme with full-page caching (Performance and Caching) is fast, and the Interactivity API adds client-side behaviour without leaving WordPress.

The costs are the same on every project:

Traditional. WordPress renders every page with its theme; interactivity comes from theme scripts or Interactivity API blocks. One application, one deployment, and every plugin works.

Hybrid. WordPress still renders the pages, and selected parts become interactive or move elsewhere. The Interactivity API covers much of what used to justify a separate front end (server-rendered HTML hydrated by directives, shared state, client-side navigation); a separate app serves one area. Lumen Press is hybrid: the block theme lumen keeps serving lumenpress.example (with lumen/wishlist as an interactive block), and the reader app adds a fast, app-like catalogue on its own host.

Fully decoupled. WordPress only serves the admin and the API (often on a host the public never sees), the front end renders every page, and WordPress’s sitemaps, feeds and front-end URLs are turned off or redirected.

The figure shows the reader app and the five flows between it and WordPress that the rest of the page builds.

The REST API is core and needs no plugin: the lp_book type is registered with 'show_in_rest' => true, and its meta with show_in_rest (Custom Post Types and Taxonomies, Metadata and Custom Fields). GraphQL, through WPGraphQL, is the main alternative (WPGraphQL and Faust.js).

The plugin gains one class, Lumen\Catalog\Headless (PSR-4 autoloaded, booted from Plugin::boot() with Headless::boot();), with a signed revalidation webhook, a preview hand-off with a short-lived signed token, and a CORS allow-list. The reader’s address and the shared secret are configuration in wp-config.php:

Source: Advanced Administration Handbook: wp-config.php

The reader gets the same value as READER_SECRET. Generate one per environment (openssl rand -hex 32) and keep it in the platform’s secret store. Without both constants the class registers nothing, so a restored copy of production on a laptop never calls production’s reader.

Source: Code Reference: save_post_{post_type}

Why each hook is the one it is:

The reader is a Next.js App Router application that talks to WordPress only from its server, so no credential or internal address reaches the browser.

Source: Next.js Docs: Installation

Configuration comes from five server-side environment variables, set in .env.local (never committed) locally and in the platform’s secret store in production: WORDPRESS_URL (https://lumenpress.example), READER_URL (https://reader.lumenpress.example), READER_SECRET (the same value as LUMEN_READER_SECRET), WP_PREVIEW_USER (lena.catalogue) and WP_PREVIEW_APP_PASSWORD (an application password, see Draft previews). Without the NEXT_PUBLIC_ prefix, Next.js never inlines them into client JavaScript (Next.js Docs: Environment Variables).

With revalidate: 3600 alone, a corrected ISBN shows up to an hour late. The webhook from Headless::send_revalidation() reaches a Route Handler that checks the signature and invalidates the lp_book tag:

Source: Node.js Docs: Crypto

Source: Next.js Docs: revalidateTag

The signature covers the raw body (request.text(), before parsing) and is compared in constant time. Since Next.js 16 revalidateTag() takes a second argument (the one-argument form is deprecated). With the recommended 'max' profile the tag is marked stale: the next visitor still gets the old page while it regenerates, and later visitors the new one; { expire: 0 } makes the next request wait for fresh data instead. One tag suits a few hundred books; a larger catalogue adds per-book tags such as book-${id}.

Checked end to end: maria.editor changed the page count of "The Lighthouse Ledger" from 312 to 320 through the REST API (as the block editor does). The reader page, a HIT with 312 pages before, answered x-nextjs-cache: STALE with 312 pages until the background regeneration finished (a second or so), then HIT with 320. Without the webhook it would have stayed at 312 for up to an hour. Setting "The Glass Orchard" back to draft with wp post update 7 --post_status=draft (WP-CLI fires the same hook) gave one stale 200 for its page, then 404, and removed it from /books. A request with a wrong X-Lumen-Signature returned 401 with {"revalidated":false}; one signed with openssl dgst -sha256 -hmac "$READER_SECRET" over the body returned 200 with {"revalidated":true,"id":5,...}.

Pitfalls: an untagged fetch is never invalidated; replicas need a shared cache handler (Deployment); a failing signature usually means re-serialised JSON or a trailing newline in a secret; slow saves mean the reader is down. Genres or authors shown by the reader need their own hooks (such as edited_lp_genre) feeding the same queue.

WordPress’s Preview button opens the theme, authenticated by the editor’s login cookie, which belongs to lumenpress.example and which the reader must not accept anyway. Lumen Press splits the problem in two:

The redirect, rather than the preview_post_link filter, is needed because the block editor builds the preview URL of a draft from the post’s link plus preview=true, using the filtered link from the autosave response only for published posts. Both URLs reach WordPress’s front end with is_preview() true, so one redirect covers both.

The preview Route Handler and page:

Source: Next.js Docs: Draft Mode

Source: Next.js Docs: Draft Mode

draftMode() is asynchronous since Next.js 15. enable() sets the __prerender_bypass cookie (a new value per next build), and requests carrying it skip the static cache; the cookie is Secure and SameSite=None, so browsers keep it only over HTTPS. The "Exit preview" form posts to app/api/exit-preview/route.ts, whose POST handler calls (await draftMode()).disable() and answers 303 to /books. Previews use their own route by ID, because a draft may have no slug yet and must never be cached under a public URL. getPreviewBook() also reads /wp/v2/lp_book/<id>/autosaves (present because lp_book supports revisions) and shows the newest autosave when it is newer than the book; autosaves hold title, content and excerpt, so meta changes appear once saved.

On the test site, previewing the draft "The Quiet Lighthouse" (ID 8) as lena.catalogue gave 302 to /api/preview?id=8&expires=1793216408&sig=6be3b79a..., then 307 to /preview/books/8 with Set-Cookie: __prerender_bypass=<value>; Path=/; Secure; HttpOnly; SameSite=none, then 200 with the draft text and <meta name="robots" content="noindex, nofollow">. Without the cookie the page was 404; the same signature with id=5 was 401; the WordPress preview URL without a login was 404. An autosave by maria.editor on the published "The Lighthouse Ledger" (title "The Lighthouse Ledger (revised)") appeared in the preview while the public page kept the published title, and did not call the webhook, since save_post_lp_book does not fire for revisions.

Server-to-server requests are not subject to CORS, so the reader’s own fetches never need it. CORS matters only when JavaScript on reader.lumenpress.example calls lumenpress.example directly, for example a search box querying /wp/v2/lp_book?search= as the reader types.

By default WordPress echoes any request’s Origin in Access-Control-Allow-Origin with Access-Control-Allow-Credentials: true (rest_send_cors_headers(), attached to rest_pre_serve_request by rest_api_default_filters() on rest_api_init). Cookie authentication stays safe because a request without the wp_rest nonce is anonymous, but a public catalogue needs less. Headless::replace_cors_headers() removes core’s callback at priority 15, after core added it, and allows only the origins of the lumen_catalog_cors_origins filter (the reader by default), read-only and without credentials. On the test site the reader’s origin received Access-Control-Allow-Origin: http://reader.lumenpress.test:3000 and Access-Control-Allow-Methods: OPTIONS, GET (also on an OPTIONS preflight, status 200), while Origin: https://evil.example received no Allow-Origin, so browsers block the read. Both kept core’s Access-Control-Expose-Headers: X-WP-Total, X-WP-TotalPages, Link and Access-Control-Allow-Headers (filters rest_exposed_cors_headers, rest_allowed_cors_headers) and Vary: Origin, which stops a CDN from serving one origin’s headers to another. CORS is a browser rule, not access control: private data is protected by permission callbacks (CORS).

Credentials follow one rule: browser code never holds a WordPress credential. Application passwords and the revalidation secret stay on the reader’s server. Reader accounts need the user’s own identity, which a cookie on lumenpress.example cannot give another site: use an OAuth or OpenID Connect provider shared by both (WordPress needs a plugin, see OAuth for Browser-Based Apps), a token plugin, or keep signed-in features on WordPress, as Lumen Press does with lumen/wishlist.

Two hosts showing the same book is duplicate content unless one is canonical. While WordPress still publishes lumenpress.example/books/<slug>/, the reader sets alternates.canonical to the REST link, rendered on the test site as <link rel="canonical" href="http://lumenpress.test/books/the-lighthouse-ledger/"/>, and WordPress’s canonical tags and sitemaps keep working (SEO, Analytics and Privacy). Fully decoupled, the direction flips: the canonical points to the reader, which publishes the sitemap from the same tagged fetch, so the webhook refreshes it too:

Source: Next.js Docs: sitemap.xml

The test build produced <loc>http://reader.lumenpress.test:3000/books/the-lighthouse-ledger</loc>; with <lastmod>2026-10-28T19:32:08Z</lastmod> (modified_gmt has no zone, hence the Z). WordPress then stops advertising its front end: add_filter( 'wp_sitemaps_enabled', '__return_false' ); turns core’s sitemaps off, "Discourage search engines" or an X-Robots-Tag: noindex header keeps the CMS host out of results, and old URLs redirect permanently to the reader, which also renders the Book JSON-LD.

Source: Code Reference: wp_sitemaps_enabled

The reader has its own pipeline (Deployment & Self-Hosting). Points specific to a WordPress back end:

Source: Next.js Docs: Self-Hosting

The two best-known alternatives to the core REST API are ecosystem projects with their own release cycles. WPGraphQL (plugin wp-graphql 2.25.0 on 2026-10-28; its WordPress.org listing describes it as becoming a canonical plugin, supported by Automattic) adds a GraphQL schema at /graphql, so a client fetches exactly the fields and relations it needs (a book, its cover, genres and the author’s other books) in one request. Post types, taxonomies and meta must be exposed with show_in_graphql, and HTTP caching takes more work than for REST GET URLs. Faust.js (WP Engine; @faustwp/core and @faustwp/cli 4.1.0, companion plugin faustwp 1.9.1) is a Next.js toolkit on top of WPGraphQL that provides what this page builds by hand: authentication, previews, a front-end template hierarchy, and blocks mapped to React components through WPGraphQL Content Blocks.

WordPress All-in-One For Dummies and Pro WordPress do not cover REST development, and Ultimate WordPress Handbook covers REST basics only, so the headless-specific points here (unfiltered content.rendered, core’s permissive CORS headers, previews, cache invalidation) complement rather than correct them. Older tutorials also predate application passwords (5.6), asynchronous draftMode() (Next.js 15), the required profile argument of revalidateTag() and the optimiser’s private-address check (both Next.js 16).