Name	Name	Last commit message	Last commit date
parent directory ..
angular/template-hierarchy-data-fetching	angular/template-hierarchy-data-fetching
astro/template-hierarchy-data-fetching-urql	astro/template-hierarchy-data-fetching-urql
basic-cli	basic-cli
next	next
nuxt	nuxt
sveltekit/template-hierarchy-data-fetching-urql	sveltekit/template-hierarchy-data-fetching-urql
LICENSE.md	LICENSE.md
README.md	README.md

HWP Toolkit Examples

This directory contains examples demonstrating how to use various features of the Headless WordPress Toolkit.

Feature Highlight: Most examples include a wp-env setup, allowing you to fully configure your headless application with a single command. They also contain screenshots of the application.

Astro Examples

Title	Description
template-hierarchy-data-fetching-urql	Demonstrates template hierarchy and data fetching with Astro, URQL, and Headless WordPress.

Next.js Examples

Title	Description
apollo-authentication	Showcases authentication with Next.js, Apollo Client, and Headless WordPress.
apollo-client-data-fetch	Explores data fetching strategies and state management using Next.js, Apollo Client, and Headless WordPress.
apollo-client-filesystem-routing	Integrates WPGraphQL and WPGraphQL for ACF with Next.js for a headless WordPress site.
client-app-router-fetch-data	Uses Next.js App Router and fetch API to retrieve data from WordPress via WPGraphQL.
client-multisite-app-router-fetch-data	Implements a multisite headless WordPress app with Next.js App Router and fetch API.
custom-sitemap-apollo	Generates a custom sitemap using Next.js, Apollo Client, and WPGraphQL with an extended plugin.
custom-sitemap-vanilla-wpgraphql	Creates a custom sitemap using Next.js and WPGraphQL without extending its endpoints.
hybrid-sitemap-apollo	Fetches and transforms WordPress sitemaps for clean URL formatting with Next.js.
proxied-sitemap-apollo	Provides a proxied sitemap by transforming WordPress XML sitemaps for SEO-friendly frontend URLs.
proxied-graphql-debug	Provides a proxied GraphQL API for development, enabling response inspection and query complexity analysis.
render-blocks-pages-router	Renders WordPress Blocks with JSX in Next.js, including utilities for hierarchical block data.
wp-theme-rendered-blocks	Demonstrates how to fetch and apply WordPress Global Styles in a Next.js project using the `globalStylesheet` GraphQL field.

SvelteKit Examples

Title	Description
template-hierarchy-data-fetching-urql	Demonstrates template hierarchy and data fetching with SvelteKit, URQL, and Headless WordPress.

Nuxt Examples

Title	Description
nuxt-headlesswp-gravity-forms	Shows you how to wire up a full headless WordPress backend—complete with Gravity Forms, WPGraphQL, and a pre-built "Questionnaire" form—alongside a Nuxt 3 front end.

Running an example

Every example has the same npm scripts. Run them from the example's directory (the one containing .wp-env.json). You'll need Docker for the local WordPress.

npm run setup   # once: install dependencies, start WordPress, import the database
npm run dev     # start WordPress and the front end

Script	What it does
`setup`	Installs dependencies, unzips any media into `wp-env/uploads`, starts WordPress and imports `wp-env/db/database.sql`. Doesn't start the front end.
`dev`	Starts WordPress and the front end.
`app:dev`	Starts only the front end. Use it to restart the app while WordPress keeps running.
`stop`	Stops WordPress. Stopping the front end doesn't stop WordPress.
`clean`	Removes the WordPress environment. Run `setup` again to start fresh.
`wp:start`	Starts only WordPress.
`db:import` / `db:export`	Imports or exports `wp-env/db/database.sql`.
`db:query`	Runs a SQL query against the WordPress database, e.g. `npm run db:query -- "SELECT 1"`.
`assets:unzip` / `assets:zip`	Unzips or re-zips `wp-env/uploads.zip`, for examples that include media.

Some examples add their own scripts on top; their READMEs list them. For any other wp-env command, use npx wp-env.

If port 8888 is already in use, for example by another wp-env site, set WP_ENV_PORT for every command, e.g. WP_ENV_PORT=8977 npm run setup, and point the front end's WordPress URL at the same port.

Contributing

If you feel like something is missing or you want to add an example for another framework, we encourage you to contribute! Please check out our Contributing Guide for more details.

Best practices for the new examples

You can copy on of existing examples to use it as a skeleton of your new example. The guide below explains the key parts our standard example format.

Project Structure

Organize your project with a clear separation between the frontend application and the WordPress environment configuration.

.
├── example-app/          # Front-end code
│   └── ...
├── .wp-env.json          # Configuration for the local WordPress environment
└── wp-env/
    └── db/
        └── database.sql  # Initial database state

Local WordPress with wp-env

Use wp-env to create a local, containerized WordPress environment. Create a .wp-env.json file in your project root and include all of the required plugins and config to make your example work:

{
  "phpVersion": "7.4",
  "plugins": ["https://downloads.wordpress.org/plugin/wp-graphql.zip"],
  "config": {
    "WP_DEBUG": true
  },
  "mappings": {
    "db": "./wp-env/db",
    "wp-content/uploads": "./wp-env/uploads",
    ".htaccess": "./wp-env/setup/.htaccess"
  },
  "lifecycleScripts": {
    "afterStart": "wp-env run cli -- wp rewrite structure '/%postname%/' && wp-env run cli -- wp rewrite flush"
  }
}

Scripts

Scripts in your package.json help automate common tasks. Use the standard scripts so every example works the same way:

"scripts": {
    "setup": "npm install && npm --prefix ./example-app install && npm run wp:start && npm run db:import",
    "dev": "npm run wp:start && npm run app:dev",
    "app:dev": "npm --prefix ./example-app run dev",
    "stop": "wp-env stop",
    "clean": "wp-env destroy",
    "wp:start": "wp-env start",
    "db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
    "db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
    "db:query": "wp-env run cli -- wp db query"
},

If the example includes media in wp-env/uploads.zip, add assets:unzip and assets:zip, and run npm run assets:unzip in setup before wp:start. See Running an example for what each script does.

Run pnpm check:examples from the repository root to check that your example follows these scripts. CI runs the same check on pull requests.

Documentation (README.md)

A clear README.md with essential information would guide the new developers effectively and reduce the errors. Consider including the information below:
- Prerequisites: Node.js, Docker.
- Setup Steps: A simple list on how to clone, install dependencies, and run the start script.
- Demo Credentials: Provide login details for the local WordPress admin (/wp-admin). Default for wp-env is admin / password.
- Security implications, and other considerations for the users, if applicable.
- Don't forget to include your example to this common README file as well, inside one of the tables above.