Use when building headless/decoupled WordPress architectures: choosing between REST API and WPGraphQL, headless authentication (JWT, application passwords, NextAuth/Auth.js), CORS configuration, frontend framework integration (Next.js, Nuxt, Astro), content webhooks, and ISR/SSG strategies.
Use this skill when building or maintaining a decoupled/headless WordPress architecture:
Run the detection script to assess the current architecture:
node skills/wp-headless/scripts/headless_inspect.mjs --cwd=/path/to/wordpress
The script outputs JSON with:
apiLayer — REST API and/or WPGraphQL availability, custom endpoints countfrontend — detected frontend framework (Next.js, Nuxt, Astro)auth — authentication methods availablecors — CORS configuration status and allowed originswebhooks — outgoing webhook configurationisHeadless — boolean assessment of whether the setup is headlessDecide between REST API (built-in) and WPGraphQL (plugin) based on project needs.
| Factor | REST API | WPGraphQL | |--------|----------|-----------| | Installation | Built-in, zero setup | Requires plugin | | Data fetching | Fixed response shape | Fetch exactly what you need | | Related data | Multiple requests | Single query with connections | | Learning curve | Low (familiar HTTP) | Medium (GraphQL syntax) | | Caching | Simple (HTTP cache) | Complex (query-level) | | Best for | Simple sites, mobile apps | Complex content, performance-critical |
Use REST with _fields parameter for simple needs. Use WPGraphQL for complex content models.
Read: references/api-layer-choice.md
For REST endpoint development, also reference the wp-rest-api skill.
If using WPGraphQL:
wp plugin install wp-graphql --activate/graphql endpoint with GraphiQLfirst/after)Read: references/wpgraphql.md
Choose the authentication method based on use case:
For security best practices in authentication, reference the wp-security skill.
Read: references/headless-auth.md
Configure Cross-Origin Resource Sharing to allow the frontend to access WordPress APIs:
add_filter('allowed_http_origins', function($origins) {
$origins[] = 'https://frontend.example.com';
return $origins;
});
Key rules:
Access-Control-Allow-Origin: * with credentialsOPTIONS requestsRead: references/cors-config.md
Connect the frontend framework to WordPress data:
fetch() in App Router with revalidate, getStaticProps in Pages Router, ISR for incremental updatesuseFetch() / useAsyncData(), ISR with routeRulesCommon patterns: centralized API client, TypeScript types from schema, image optimization with WordPress media URLs.
Read: references/frontend-integration.md
Trigger frontend rebuilds or cache invalidation when WordPress content changes:
add_action('transition_post_status', function($new, $old, $post) {
if ($new === 'publish') {
wp_remote_post('https://frontend.example.com/api/revalidate', [
'body' => json_encode(['path' => '/' . $post->post_name]),
'headers' => ['Content-Type' => 'application/json', 'Authorization' => 'Bearer SECRET'],
]);
}
}, 10, 3);
Strategies: path-based ISR, tag-based revalidation, full rebuild triggers. WPGraphQL Smart Cache provides automatic invalidation.
Read: references/webhooks.md
curl https://wp.example.com/wp-json/wp/v2/posts returns JSONAccess-Control-Allow-Origin in response headersnext build / nuxt generate / astro build completesuser:xxxx xxxx xxxx), check JWT token expiry, confirm Authorization header is forwardedrevalidate interval too high; webhook not triggering; check transition_post_status hook fires on publishshow_in_graphql => true; ACF fields need WPGraphQL for ACF extensionwp-rest-api skillwp-security skillwp-webhooks skillwp-programmatic-seo skillSearch for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer