claude-plugin-wordpress-manager 1.5.0 → 1.7.1

package/skills/wp-headless/references/cors-config.md

@@ -0,0 +1,245 @@
+# CORS Configuration
+
+Use this file when configuring Cross-Origin Resource Sharing for headless WordPress.
+
+## Why CORS matters for headless
+
+In a headless setup, the frontend (e.g., `app.example.com`) and WordPress backend (`wp.example.com`) are on different origins. Browsers block cross-origin requests unless the server explicitly allows them via CORS headers.
+
+## WordPress CORS via PHP
+
+### Allow specific origin (recommended)
+
+```php
+add_action('init', function() {
+    $allowed_origins = [
+        'https://app.example.com',
+        'https://staging.example.com',
+    ];
+
+    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
+
+    if (in_array($origin, $allowed_origins, true)) {
+        header("Access-Control-Allow-Origin: $origin");
+        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+        header('Access-Control-Allow-Headers: Authorization, Content-Type, X-WP-Nonce');
+        header('Access-Control-Allow-Credentials: true');
+        header('Access-Control-Max-Age: 86400');
+    }
+
+    // Handle preflight
+    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
+        status_header(204);
+        exit;
+    }
+});
+```
+
+### REST API specific filter
+
+```php
+add_action('rest_api_init', function() {
+    remove_filter('rest_pre_serve_request', 'rest_send_cors_headers');
+
+    add_filter('rest_pre_serve_request', function($value) {
+        $allowed_origins = [
+            'https://app.example.com',
+            'https://staging.example.com',
+        ];
+
+        $origin = get_http_origin();
+
+        if ($origin && in_array($origin, $allowed_origins, true)) {
+            header("Access-Control-Allow-Origin: $origin");
+            header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+            header('Access-Control-Allow-Headers: Authorization, Content-Type, X-WP-Nonce');
+            header('Access-Control-Allow-Credentials: true');
+        }
+
+        return $value;
+    });
+});
+```
+
+### WPGraphQL CORS
+
+```php
+add_action('graphql_response_headers_to_send', function($headers) {
+    $allowed_origins = [
+        'https://app.example.com',
+    ];
+
+    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
+
+    if (in_array($origin, $allowed_origins, true)) {
+        $headers['Access-Control-Allow-Origin'] = $origin;
+        $headers['Access-Control-Allow-Headers'] = 'Authorization, Content-Type';
+        $headers['Access-Control-Allow-Credentials'] = 'true';
+    }
+
+    return $headers;
+});
+```
+
+## Server-level CORS
+
+### Nginx
+
+```nginx
+# /etc/nginx/conf.d/cors.conf or within server block
+map $http_origin $cors_origin {
+    default "";
+    "https://app.example.com"     "https://app.example.com";
+    "https://staging.example.com" "https://staging.example.com";
+}
+
+server {
+    # ... existing config
+
+    location /wp-json/ {
+        if ($cors_origin != "") {
+            add_header Access-Control-Allow-Origin $cors_origin always;
+            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
+            add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-WP-Nonce" always;
+            add_header Access-Control-Allow-Credentials "true" always;
+            add_header Access-Control-Max-Age 86400 always;
+        }
+
+        if ($request_method = OPTIONS) {
+            return 204;
+        }
+
+        # ... proxy or fastcgi config
+    }
+
+    location /graphql {
+        # Same CORS headers as above
+        if ($cors_origin != "") {
+            add_header Access-Control-Allow-Origin $cors_origin always;
+            add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
+            add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
+            add_header Access-Control-Allow-Credentials "true" always;
+        }
+
+        if ($request_method = OPTIONS) {
+            return 204;
+        }
+
+        # ... proxy or fastcgi config
+    }
+}
+```
+
+### Apache (.htaccess)
+
+```apache
+<IfModule mod_headers.c>
+    SetEnvIf Origin "^https://(app|staging)\.example\.com$" CORS_ORIGIN=$0
+    Header always set Access-Control-Allow-Origin %{CORS_ORIGIN}e env=CORS_ORIGIN
+    Header always set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
+    Header always set Access-Control-Allow-Headers "Authorization, Content-Type, X-WP-Nonce"
+    Header always set Access-Control-Allow-Credentials "true"
+    Header always set Access-Control-Max-Age "86400"
+</IfModule>
+
+# Handle preflight
+RewriteEngine On
+RewriteCond %{REQUEST_METHOD} OPTIONS
+RewriteRule ^(.*)$ $1 [R=204,L]
+```
+
+## CORS headers explained
+
+| Header | Purpose |
+|--------|---------|
+| `Access-Control-Allow-Origin` | Which origins can access the resource |
+| `Access-Control-Allow-Methods` | Which HTTP methods are allowed |
+| `Access-Control-Allow-Headers` | Which request headers are allowed |
+| `Access-Control-Allow-Credentials` | Whether cookies/auth can be sent |
+| `Access-Control-Max-Age` | How long preflight results can be cached (seconds) |
+| `Access-Control-Expose-Headers` | Which response headers the client can read |
+
+## Common issues
+
+### "No 'Access-Control-Allow-Origin' header"
+
+The server doesn't include the CORS header. Fix: add the headers as shown above.
+
+### "The value of 'Access-Control-Allow-Origin' is not equal to the supplied origin"
+
+Origin mismatch. Check:
+- Trailing slashes (`https://app.example.com` vs `https://app.example.com/`)
+- Protocol (`http` vs `https`)
+- Port numbers (`localhost:3000` vs `localhost`)
+
+### "Credentials flag is true but Access-Control-Allow-Origin is '*'"
+
+Cannot use `*` with `credentials: true`. Must specify the exact origin:
+```
+Access-Control-Allow-Origin: https://app.example.com  ✓
+Access-Control-Allow-Origin: *                          ✗ (with credentials)
+```
+
+### Preflight (OPTIONS) returns 401/403
+
+WordPress or a security plugin is blocking OPTIONS requests. Fix:
+```php
+add_action('init', function() {
+    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
+        // Send CORS headers and exit before WordPress auth runs
+        header('Access-Control-Allow-Origin: https://app.example.com');
+        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+        header('Access-Control-Allow-Headers: Authorization, Content-Type');
+        header('Access-Control-Allow-Credentials: true');
+        status_header(204);
+        exit;
+    }
+});
+```
+
+## Development CORS
+
+```php
+// ONLY for local development — never in production
+if (defined('WP_DEBUG') && WP_DEBUG) {
+    add_action('init', function() {
+        header('Access-Control-Allow-Origin: http://localhost:3000');
+        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+        header('Access-Control-Allow-Headers: Authorization, Content-Type');
+        header('Access-Control-Allow-Credentials: true');
+
+        if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
+            status_header(204);
+            exit;
+        }
+    });
+}
+```
+
+## Security rules
+
+1. **Never use `*` in production** — always whitelist specific origins
+2. **Never reflect the Origin header blindly** — validate against a whitelist
+3. **Use `Credentials: true` only when needed** — for authenticated requests
+4. **Set `Max-Age` for caching** — reduces preflight requests (86400 = 24 hours)
+5. **Expose only needed headers** — minimize `Access-Control-Expose-Headers`
+
+## Verification
+
+```bash
+# Test CORS headers
+curl -I -X OPTIONS https://wp.example.com/wp-json/wp/v2/posts \
+  -H "Origin: https://app.example.com" \
+  -H "Access-Control-Request-Method: GET" \
+  -H "Access-Control-Request-Headers: Authorization"
+
+# Check response headers include:
+# Access-Control-Allow-Origin: https://app.example.com
+# Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+# Access-Control-Allow-Headers: Authorization, Content-Type
+
+# Test from frontend
+fetch('https://wp.example.com/wp-json/wp/v2/posts', {
+    credentials: 'include',
+}).then(r => console.log('CORS OK:', r.ok));
+```

package/skills/wp-headless/references/frontend-integration.md

@@ -0,0 +1,331 @@
+# Frontend Integration
+
+Use this file when connecting a JavaScript frontend framework to a headless WordPress backend.
+
+## Next.js integration
+
+### Data fetching (App Router)
+
+```js
+// lib/wordpress.js
+const WP_URL = process.env.NEXT_PUBLIC_WP_URL || 'https://wp.example.com';
+
+export async function getPosts(page = 1, perPage = 10) {
+    const res = await fetch(
+        `${WP_URL}/wp-json/wp/v2/posts?page=${page}&per_page=${perPage}&_embed`,
+        { next: { revalidate: 60 } } // ISR: revalidate every 60 seconds
+    );
+    if (!res.ok) throw new Error('Failed to fetch posts');
+    return {
+        posts: await res.json(),
+        totalPages: Number(res.headers.get('X-WP-TotalPages')),
+    };
+}
+
+export async function getPost(slug) {
+    const res = await fetch(
+        `${WP_URL}/wp-json/wp/v2/posts?slug=${slug}&_embed`,
+        { next: { revalidate: 60 } }
+    );
+    const posts = await res.json();
+    return posts[0] || null;
+}
+
+export async function getPage(slug) {
+    const res = await fetch(
+        `${WP_URL}/wp-json/wp/v2/pages?slug=${slug}&_embed`,
+        { next: { revalidate: 300 } }
+    );
+    const pages = await res.json();
+    return pages[0] || null;
+}
+```
+
+### Page components
+
+```jsx
+// app/blog/page.js
+import { getPosts } from '@/lib/wordpress';
+
+export default async function BlogPage() {
+    const { posts } = await getPosts();
+
+    return (
+        <main>
+            <h1>Blog</h1>
+            {posts.map((post) => (
+                <article key={post.id}>
+                    <h2>
+                        <a href={`/blog/${post.slug}`}>{post.title.rendered}</a>
+                    </h2>
+                    <div dangerouslySetInnerHTML={{ __html: post.excerpt.rendered }} />
+                </article>
+            ))}
+        </main>
+    );
+}
+
+// app/blog/[slug]/page.js
+import { getPost, getPosts } from '@/lib/wordpress';
+import { notFound } from 'next/navigation';
+
+export async function generateStaticParams() {
+    const { posts } = await getPosts(1, 100);
+    return posts.map((post) => ({ slug: post.slug }));
+}
+
+export default async function PostPage({ params }) {
+    const post = await getPost(params.slug);
+    if (!post) notFound();
+
+    return (
+        <article>
+            <h1>{post.title.rendered}</h1>
+            <div dangerouslySetInnerHTML={{ __html: post.content.rendered }} />
+        </article>
+    );
+}
+```
+
+### ISR (Incremental Static Regeneration)
+
+```js
+// Revalidate on demand via webhook (see webhooks.md)
+// app/api/revalidate/route.js
+import { revalidatePath } from 'next/cache';
+
+export async function POST(request) {
+    const secret = request.headers.get('x-revalidate-secret');
+    if (secret !== process.env.REVALIDATE_SECRET) {
+        return Response.json({ error: 'Invalid secret' }, { status: 401 });
+    }
+
+    const { path } = await request.json();
+    revalidatePath(path);
+    return Response.json({ revalidated: true });
+}
+```
+
+## Nuxt 3 integration
+
+### Composable
+
+```js
+// composables/useWordPress.js
+export function useWordPress() {
+    const config = useRuntimeConfig();
+    const wpUrl = config.public.wpUrl;
+
+    async function getPosts(page = 1) {
+        return useFetch(`${wpUrl}/wp-json/wp/v2/posts`, {
+            params: { page, per_page: 10, _embed: true },
+        });
+    }
+
+    async function getPost(slug) {
+        const { data } = await useFetch(`${wpUrl}/wp-json/wp/v2/posts`, {
+            params: { slug, _embed: true },
+        });
+        return data.value?.[0] || null;
+    }
+
+    return { getPosts, getPost };
+}
+```
+
+### nuxt.config.ts
+
+```ts
+export default defineNuxtConfig({
+    runtimeConfig: {
+        public: {
+            wpUrl: process.env.WP_URL || 'https://wp.example.com',
+        },
+    },
+    routeRules: {
+        '/blog/**': { isr: 60 }, // Revalidate every 60s
+        '/': { isr: 300 },
+    },
+});
+```
+
+## Astro integration
+
+### Data fetching
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import Layout from '@/layouts/Layout.astro';
+
+export async function getStaticPaths() {
+    const res = await fetch(`${import.meta.env.WP_URL}/wp-json/wp/v2/posts?per_page=100`);
+    const posts = await res.json();
+
+    return posts.map((post) => ({
+        params: { slug: post.slug },
+        props: { post },
+    }));
+}
+
+const { post } = Astro.props;
+---
+
+<Layout title={post.title.rendered}>
+    <article>
+        <h1 set:html={post.title.rendered} />
+        <div set:html={post.content.rendered} />
+    </article>
+</Layout>
+```
+
+## WPGraphQL with frontend frameworks
+
+### Apollo Client (React/Next.js)
+
+```js
+// lib/apollo.js
+import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client';
+
+const client = new ApolloClient({
+    link: new HttpLink({
+        uri: `${process.env.NEXT_PUBLIC_WP_URL}/graphql`,
+    }),
+    cache: new InMemoryCache(),
+});
+
+export default client;
+```
+
+### urql (lightweight alternative)
+
+```js
+import { Client, cacheExchange, fetchExchange } from 'urql';
+
+const client = new Client({
+    url: `${process.env.NEXT_PUBLIC_WP_URL}/graphql`,
+    exchanges: [cacheExchange, fetchExchange],
+});
+```
+
+## Rendering WordPress content
+
+### Sanitizing HTML content
+
+```jsx
+// React: dangerouslySetInnerHTML (ensure source is trusted)
+<div dangerouslySetInnerHTML={{ __html: post.content.rendered }} />
+
+// With DOMPurify for extra safety
+import DOMPurify from 'isomorphic-dompurify';
+
+function WPContent({ html }) {
+    const clean = DOMPurify.sanitize(html, {
+        ADD_TAGS: ['iframe'],
+        ADD_ATTR: ['allow', 'allowfullscreen', 'frameborder', 'scrolling'],
+    });
+    return <div dangerouslySetInnerHTML={{ __html: clean }} />;
+}
+```
+
+### Handling WordPress images
+
+```jsx
+// Replace WordPress image URLs with optimized versions
+function optimizeImages(html, wpUrl) {
+    // Replace with Next.js Image optimization
+    return html.replace(
+        /src="([^"]*wp-content\/uploads\/[^"]*)"/g,
+        (match, url) => `src="/_next/image?url=${encodeURIComponent(url)}&w=1200&q=80"`
+    );
+}
+```
+
+### WordPress blocks in React
+
+```jsx
+// Parse block content into React components
+function renderBlock(block) {
+    switch (block.blockName) {
+        case 'core/paragraph':
+            return <p dangerouslySetInnerHTML={{ __html: block.innerHTML }} />;
+        case 'core/heading':
+            return <h2 dangerouslySetInnerHTML={{ __html: block.innerHTML }} />;
+        case 'core/image':
+            return <figure dangerouslySetInnerHTML={{ __html: block.innerHTML }} />;
+        default:
+            return <div dangerouslySetInnerHTML={{ __html: block.innerHTML }} />;
+    }
+}
+```
+
+## SEO in headless WordPress
+
+### Yoast SEO integration
+
+```js
+// Fetch Yoast data from REST API
+// Requires Yoast SEO plugin (adds yoast_head to REST responses)
+export async function getPostSEO(slug) {
+    const res = await fetch(
+        `${WP_URL}/wp-json/wp/v2/posts?slug=${slug}&_fields=yoast_head_json`
+    );
+    const posts = await res.json();
+    return posts[0]?.yoast_head_json || {};
+}
+```
+
+```jsx
+// app/blog/[slug]/page.js
+export async function generateMetadata({ params }) {
+    const seo = await getPostSEO(params.slug);
+    return {
+        title: seo.title,
+        description: seo.description,
+        openGraph: {
+            title: seo.og_title,
+            description: seo.og_description,
+            images: seo.og_image ? [{ url: seo.og_image[0].url }] : [],
+        },
+    };
+}
+```
+
+## Preview mode
+
+```js
+// app/api/preview/route.js (Next.js)
+import { draftMode } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+export async function GET(request) {
+    const { searchParams } = new URL(request.url);
+    const secret = searchParams.get('secret');
+    const slug = searchParams.get('slug');
+
+    if (secret !== process.env.WP_PREVIEW_SECRET) {
+        return Response.json({ error: 'Invalid secret' }, { status: 401 });
+    }
+
+    draftMode().enable();
+    redirect(`/blog/${slug}`);
+}
+```
+
+## Verification
+
+```bash
+# Test REST API from frontend origin
+curl -H "Origin: https://app.example.com" \
+  https://wp.example.com/wp-json/wp/v2/posts?per_page=1
+
+# Test _embed returns featured images
+curl -s "https://wp.example.com/wp-json/wp/v2/posts?_embed&per_page=1" | \
+  jq '.[0]._embedded["wp:featuredmedia"][0].source_url'
+
+# Test ISR revalidation
+curl -X POST https://app.example.com/api/revalidate \
+  -H "Content-Type: application/json" \
+  -H "x-revalidate-secret: YOUR_SECRET" \
+  -d '{"path": "/blog/hello-world"}'
+```