N
HeadlessCoreHeadless Core
Back to Home

Getting Started

This guide walks you through running HeadlessCore locally on XAMPP (Windows), Docker, or any PHP + MySQL stack. Total time: ~15 minutes.

Prerequisites

Requirement Version
PHP 8.0+
MySQL / MariaDB 5.7+
Node.js 20+
npm or pnpm Latest

Optional: Docker Desktop for the all-in-one stack.

Step 1 — WordPress

  1. Place this repository under your web root (e.g. C:\xampp\htdocs\headleespro).
  2. Create a MySQL database (e.g. headleespro).
  3. Copy wp-config-sample.php → wp-config.php and set database credentials.
  4. Open http://localhost/headleespro and complete the WordPress installer.
  5. Log in to wp-admin.

Step 2 — Activate theme & plugins

  1. Go to Appearance → Themes and activate HeadlessCore.
  2. A TGMPA notice will appear — install and activate:
    • WPGraphQL
    • WPGraphQL JWT Authentication
  3. Verify GraphQL works: open http://localhost/headleespro/graphql in your browser or GraphiQL IDE.

Step 3 — Configure HeadlessCore

  1. Open Headless Core → Settings in wp-admin.
  2. Set Next.js Frontend URL to http://localhost:3000.
  3. Choose a Home Page Layout — see Site Modes for all 8 options.
  4. Generate secrets (run twice for two different values):
openssl rand -base64 32
WordPress field Next.js env var
Revalidation Secret REVALIDATION_SECRET
Preview Secret PREVIEW_SECRET
  1. (Optional) Set Contact Webhook URL for Slack/Discord notifications on form submit.

Step 4 — Next.js frontend

cd nextjs-starter-kit
cp .env.example .env.local

Edit .env.local:

NEXT_PUBLIC_WORDPRESS_API_URL=http://localhost/headleespro/graphql
NEXT_PUBLIC_WORDPRESS_URL=http://localhost/headleespro
NEXT_PUBLIC_SITE_URL=http://localhost:3000
REVALIDATION_SECRET=your-secret-here
PREVIEW_SECRET=your-preview-secret-here
WORDPRESS_AUTH_TOKEN=

Start the dev server:

npm install
npm run dev

Open http://localhost:3000.

Tip: If WordPress is not running, the frontend automatically falls back to mock data from src/lib/mockData.ts. A banner indicates mock mode.

Step 5 — Add sample content

Option A: One-click demo importer (recommended)

  1. Go to Headless Core → Settings.
  2. Scroll to Import Demo Content.
  3. Click Import Demo Content — creates posts, services, projects, testimonials, team, FAQ, pricing, and products.

Option B: Manual content

Content type Where to create
Blog posts Posts
Corporate services Headless Core → Corporate Services
Case studies Headless Core → Case Studies
Portfolio projects Headless Core → Portfolio Projects
Testimonials Headless Core → Testimonials
Shop products Headless Core → Shop Products
Team members Headless Core → Team Members
FAQ items Headless Core → FAQ
Pricing plans Headless Core → Pricing Plans
Navigation Appearance → Menus → assign to Primary Navigation

Step 6 — Verify everything works

cd nextjs-starter-kit
npm test        # 9 unit tests
npm run build   # Production build check

Check the HeadlessCore Status widget on the WordPress dashboard for connection health.

Alternative: Docker

docker compose up -d
  • WordPress: http://localhost:8080
  • MySQL: port 3306
  • Theme is volume-mounted from wp-content/themes/wp-headless-theme/

See ../docker-compose.yml for full configuration.

Alternative: Scaffold CLI

From the repo root:

npm run create my-client-site

Or after npm publish:

npx create-headlesscore my-client-site --wordpress-url=http://localhost/headleespro

This copies the Next.js template, generates .env.local with random secrets, and runs npm install. See CLI Scaffold.

Explore the 8 site modes

Mode Demo URL
Multi-demo showcase /
Blog /blog
Corporate /corporate
Portfolio /portfolio
Business /business
Landing /landing
Shop /shop
WordPress Page Set in WP admin

Set Home Page Layout in WordPress to make any mode your homepage.

Next steps