HeadlessNext Documentation
HeadlessNext is a free, GPL-licensed WordPress theme and connector pair — independent from HeadlessCore, and built for anyone who wants headless capability without buying into a full starter kit. This page covers installing both pieces and configuring every setting.
Requirements
- WordPress 6.4 or later
- PHP 7.4 or later
Part 1 — The HeadlessNext theme (free)
A clean, general-purpose block-ready theme for blogs, portfolios, and small business sites. It intentionally ships with:
- No custom post types
- No settings pages
- No license-gated functionality
It’s a theme in the traditional WordPress sense — full block editor support (title-tag, post thumbnails, wide/full alignment, editor styles, custom logo, widget areas), accessible semantic markup, and nothing else. It works completely standalone with only WordPress core; no plugin is required to use it.
Installing the theme
- In wp-admin: Appearance → Themes → Add New → Upload Theme.
- Select the theme ZIP and click Install Now.
- Click Activate.
- Under Appearance → Customize, set your site logo, colors, and
menus as you would with any classic WordPress theme.
The theme works immediately with no further configuration — it has no settings page by design.
Part 2 — The HeadlessNext Connector (free)
An independent plugin that adds decoupled front-end capability to any theme — it does not require the HeadlessNext theme, and the theme does not require it. Install it only if you’re pointing a separate front-end (Next.js or otherwise) at this WordPress site.
Installing the Connector
- In wp-admin: Plugins → Add New → Upload Plugin.
- Select the plugin ZIP, click Install Now, then Activate.
- Go to the plugin’s settings page and configure the four fields below.
Settings reference
| Field | What it does |
|---|---|
| Frontend URL | The base URL of your decoupled frontend (e.g. https://example.com). Must be a complete, valid URL. If left empty, the plugin makes zero outgoing requests. |
| Revalidation Path | The path on your frontend that accepts revalidation requests, appended to the Frontend URL above. |
| Revalidation Secret | A shared secret sent with every revalidation request so your frontend can verify it actually came from this WordPress site. |
| Automatic Revalidation | When enabled, saving or publishing content automatically triggers a revalidation request. When disabled, you trigger revalidation manually. |
How revalidation works
When Automatic Revalidation is on and a post or page is saved, the Connector sends a request to Frontend URL + Revalidation Path, including the Revalidation Secret. Your frontend verifies the secret and regenerates the affected page. If Frontend URL is empty, none of this fires — the plugin stays completely inert.
Free vs. Pro
| Connector (free) | Connector Pro | |
|---|---|---|
| Frontend URL + path config | ✅ | ✅ |
| Automatic revalidation | ✅ | ✅ |
| Request authentication | Shared secret | HMAC-signed webhooks |
| Delivery visibility | None | Delivery log |
| Multi-site licensing | — | Seats for agencies |
Upgrading to Connector Pro
If you need production-grade webhook signing, a delivery log, or multi-site licensing across several client sites, see the HeadlessNext Connector Pro documentation. Pro requires the free Connector plugin active — it’s an upgrade, not a replacement.
Support
Report bugs via the theme or plugin’s WordPress.org support forum.