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

0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/shahbaz342k/headless-wp-connector/archive/refs/heads/main.zip

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

Clone or download this repo into wp-content/plugins/
Activate Headless WP Connector in your WordPress admin
Go to Headless Connector in the sidebar and set your frontend URL

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"}'

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