N
HeadlessCoreHeadless Core
Back to Home

HeadlessCore Documentation

HeadlessCore pairs a WordPress theme with a Next.js 16 starter kit, connected over WPGraphQL, so you can run a fast, decoupled site without building the plumbing yourself. This page covers installation end to end, every configuration value you’ll need, the full pro block catalog, and how licensing works.

What’s included

  • WordPress theme + Next.js 16 starter kit
  • 47 pro Gutenberg blocks (see the full catalog below)
  • 8 demo layouts — blog, corporate, portfolio, shop, landing
  • ISR, on-demand revalidation, and draft preview
  • Stripe-backed license key and secure product download
  • Self-hosted — you own the code and the data, no hosting included

Requirements

  • A WordPress site (existing or new) with admin access
  • The WPGraphQL plugin (ships as a required dependency of the theme)
  • Node.js on your local machine, for running the Next.js starter kit
  • A place to deploy the frontend — Vercel works with zero config; any

Node-compatible host works too

Step-by-step installation

Step 1 — Purchase

Buy through the Stripe checkout on the HeadlessCore product page. Payment mints a license key (hc1. prefix) tied to your email, delivered instantly by email and shown on the confirmation page. Keep it — you’ll paste it in two places below.

Step 2 — Download the product

Go to the download page and paste your license key. This unlocks the current release ZIP, containing the WordPress theme, the Next.js starter kit source, and docs.

Step 3 — Install the WordPress theme

  1. In wp-admin: Appearance → Themes → Add New → Upload Theme.
  2. Select the theme ZIP from the download and click Install Now.
  3. Click Activate.
  4. Confirm WPGraphQL is active under Plugins — the theme

declares it as a required dependency, so it should auto-prompt if missing.

  1. Visit https://your-wordpress-site.com/graphql in a browser — you

should get a GraphQL response (not a 404), confirming the endpoint is live.

Step 4 — Configure the Next.js frontend

Unzip the starter kit locally and run npm install. Create .env.local in the project root with at minimum:

NEXT_PUBLIC_WORDPRESS_URL=https://your-wordpress-site.com
NEXT_PUBLIC_WORDPRESS_API_URL=https://your-wordpress-site.com/graphql
NEXT_PUBLIC_SITE_URL=http://localhost:3000
REVALIDATION_SECRET=choose-a-random-secret
PREVIEW_SECRET=choose-a-different-random-secret

REVALIDATION_SECRET and PREVIEW_SECRET are values you invent — they just need to match exactly what you enter in wp-admin in Step 5. Everything else in .env.example (Stripe keys, Turnstile, search provider) is optional and only needed if you’re using those specific features.

Step 5 — Match the secrets in WordPress

In wp-admin, go to Headless Core → Settings, and under the Revalidation Secret and Preview Secret fields, enter the exact same values you set in .env.local above. This is what lets WordPress authenticate its on-demand revalidation and preview requests to your Next.js app — if these don’t match, revalidation and preview will fail silently.

Step 6 — Activate your license

Still in Headless Core → Settings, scroll to the Licensing section and paste your license key into the License Key field. This unlocks product updates through the built-in updater.

Step 7 — Run and verify locally

npm run dev

Visit http://localhost:3000 and confirm your WordPress content loads. Edit a page in wp-admin and confirm the change appears after a refresh (on-demand revalidation) or within ~60 seconds (ISR fallback).

Step 8 — Deploy

Deploy the Next.js app to Vercel (or any Node host). Set the same environment variables from Step 4 in your hosting provider’s dashboard, with NEXT_PUBLIC_SITE_URL updated to your real production domain. Your WordPress install doesn’t move — it keeps serving content over GraphQL to whichever frontend URL you’ve deployed.

Full pro block catalog

All 47 blocks ship with matching Next.js renderers — add the block in wp-admin, it renders correctly on the frontend, no custom code needed.

Content & layout — Hero Banner, Feature Grid, Steps, Callout, Icon List, Icon Box, Divider, Spacer, Bento Grid, Table of Contents, Quote Block, Button Group, Magazine Category Grid, Posts Grid, Recent Posts, Blog Archive

Marketing & conversion — CTA Banner, Split CTA, Pricing Table, Pricing Toggle, Countdown Timer, Newsletter Signup, Popup, Alert Banner, Badge Row

Social proof — Testimonial Slider, Team Grid, Team Slider, Stats Counter, Logo Cloud, Logo Marquee, Star Rating, Author Box, Before/After

Interactive & forms — Tabs, FAQ Accordion, Contact Form, Comparison Table, Flip Cards, Progress Bar, Scrolling Text, Map Embed

Media — Image Gallery, Video Embed, Photo Album

Utility — Social Share, Timeline

Draft preview

  1. In wp-admin, edit a draft post or page.
  2. Click Preview — this generates a signed preview link using your

PREVIEW_SECRET.

  1. The Next.js frontend verifies the signature and renders the draft

content live, exactly as it will look once published.

  1. An amber “Preview Mode” banner appears on the page; click **Exit

Preview** to leave preview mode.

ISR and on-demand revalidation

Pages are statically generated and served instantly, then regenerated in two ways:

  • On-demand: publishing or updating content in WordPress fires a

webhook to your Next.js app (authenticated with REVALIDATION_SECRET) that regenerates just that page immediately.

  • Time-based (ISR): as a fallback, pages also revalidate on a fixed

interval even if the webhook doesn’t fire, so content never goes permanently stale.

Licensing and updates

License keys use the hc1. prefix and are tied to your purchase email. Update availability follows the license duration selected at purchase (lifetime or 1 year). See the Terms of Service & Refund Policy for the full license and refund terms.

Troubleshooting

  • GraphQL endpoint 404s or errors — confirm WPGraphQL is active and

permalinks are set to anything other than “Plain” (Settings → Permalinks).

  • Content changes don’t appear — check that REVALIDATION_SECRET in

.env.local exactly matches the value in Headless Core → Settings; a mismatch fails silently rather than throwing a visible error.

  • License key rejected — make sure you’re pasting the full key

including the hc1. prefix, with no extra whitespace.

  • Pro blocks show blank on the frontend — confirm you’re on the

current theme release; block renderers are added incrementally and an outdated download may be missing the newest ones.

Support

Installation issues, license activation, and reproducible bugs in the product itself are in scope for support — see the contact details on the Terms of Service page.