WP Manifestindependent plugin directory
manifest / integrations / headless-wp-connector

Headless WP Connector

Turn WordPress into a headless CMS — JWT auth, live draft previews, ACF & GraphQL support

by Mohd Shahbaz · github.com/shahbaz342k/headless-wp-connector

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/shahbaz342k/headless-wp-connector/archive/refs/heads/main.zip
No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.
Readme github.com/shahbaz342k/headless-wp-connector ↗

Turn WordPress into a headless CMS for React/Next.js frontends — JWT auth, live draft previews, ACF field exposure, and optional GraphQL support, out of the box.

Why this exists

Most headless WordPress setups require stitching together multiple plugins and writing custom auth/CORS/preview logic by hand. This plugin packages the common pieces every headless project needs into one lightweight tool — no external dependencies, no bloat.

Features

  • JWT Authentication — secure token-based login for the WP REST API, built with zero external libraries (pure PHP, HS256)
  • Live Draft Preview — content editors get a one-click, time-limited preview link that renders unpublished drafts on the actual frontend, before publishing
  • CORS Handling — locked to a single configured frontend origin (no wildcard *, safer by default)
  • ACF Auto-Exposure — if Advanced Custom Fields is active, its fields are automatically added to REST API responses
  • Optional GraphQL Support — if WPGraphQL is installed, exposes preview URLs directly in its schema, authenticated via the same JWT tokens

Tech Stack

  • Backend: PHP (WordPress Plugin API, REST API, custom JWT implementation)
  • Reference Frontend: Next.js (App Router) — see /example-frontend for a working preview page

Quick Start

  1. Clone or download this repo into wp-content/plugins/
  2. Activate Headless WP Connector in your WordPress admin
  3. Go to Headless Connector in the sidebar and set your frontend URL
  4. Authenticate:
    curl -X POST http://your-site.local/wp-json/headless-wp-connector/v1/token \
  -H "Content-Type: application/json" \
  -d '{"username":"your-username","password":"your-password"}'
  5. Use the returned token to call protected endpoints:
    curl http://your-site.local/wp-json/headless-wp-connector/v1/verify \
  -H "Authorization: Bearer <token>"

Architecture

┌─────────────────┐         JWT-authenticated          ┌──────────────────┐
│   WordPress      │ ◄────────  REST API calls  ──────► │  Next.js Frontend │
│  (content admin)  │                                    │   (public site)   │
└─────────────────┘                                    └──────────────────┘
        │
        │ optional
        ▼
┌─────────────────┐
│   WPGraphQL       │  ← schema extended with headlessPreviewUrl field
└─────────────────┘

API Reference

Endpoint Method Auth Description
/wp-json/headless-wp-connector/v1/token POST None Exchange username/password for a JWT
/wp-json/headless-wp-connector/v1/verify GET Bearer token Verify a token is valid
/wp-json/headless-wp-connector/v1/preview-token POST Cookie (WP admin) Generate a time-limited preview link for a post
/wp-json/headless-wp-connector/v1/preview GET Preview token Fetch draft content for rendering on the frontend

Project Structure

headless-wp-connector/
├── headless-wp-connector.php   # Plugin bootstrap
└── includes/
    ├── class-auth.php           # JWT sign/verify (no dependencies)
    ├── class-rest-api.php       # /token and /verify endpoints
    ├── class-cors.php           # Origin-locked CORS headers
    ├── class-settings.php       # Admin settings page
    ├── class-preview.php        # Draft preview token + REST endpoints
    ├── class-acf.php            # Auto-expose ACF fields via REST
    └── class-graphql.php        # Optional WPGraphQL schema extension

Roadmap

  • [ ] Multi-site license support (Pro)
  • [ ] White-label option for agencies (Pro)
  • [ ] Webhook triggers on publish/update
  • [ ] Image optimization pipeline for headless delivery

License

GPLv2 or later