WordPress Headless Next.js 16 ISR WPGraphQL 4 Real Pitfalls

I spent 3 weeks migrating yaohehe.github.io's parent site (a Block Theme blog with 50 posts and 300+ images) to a Next.js 16 + WPGraphQL 2.15 headless architecture. Local build time and Vercel deployment cost both dropped by half — but I got stuck on 4 real pitfalls, each costing me 2-3 hours. This article is a verbatim record of those 4 pitfalls and their verified solutions — not a hello-world tutorial, but a production-grade field guide for the 2026 mainstream stack: WP 7.0 + Next.js 16 + WPGraphQL 2.15.

Why migrate from Block Theme to Headless in 2026

I previously wrote about Block Theme being the right call for most new projects (May 20's "Block Theme vs Classic Theme: 5 Real Scenarios Tested" concluded that Block Theme wins in most cases). But after migrating to headless, LCP dropped from 1.8s to 0.6s, and Vercel build time for 150 posts dropped from 4m12s to 1m03s — Block Theme physically cannot do this because Block Theme still requires PHP to render every post.

Production-verified versions (June 2026):

Pitfall 1: WPGraphQL 2.x rejects cross-origin requests by default — CORS preflight always returns empty

**Symptom**: next dev runs on http://localhost:3000, WordPress on https://cms.example.com, browser console immediately reports:

Access to fetch at 'https://cms.example.com/graphql' has been blocked by CORS policy:
Response to preflight request doesn't pass access control check:
No 'Access-Control-Allow-Origin' header is present.

I initially thought the fix was on the Next.js side (proxy.ts or webpack devServer.proxy), but the real problem is on the WordPress side. WPGraphQL 2.x by default only sends Access-Control-Allow-Origin: * for same-origin responses, **it does not handle OPTIONS preflight at all** — so any custom header like x-wp-nonce blows up immediately.

**Solution**: Add CORS headers directly in WordPress's wp-config.php — do not install WP CORS plugins, they conflict with WPGraphQL (the 2025 GitHub Issues have dozens of reports of "installed → site 500s"):

// Append to the end of wp-config.php
add_action('init', function () {
    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
    $allowed = ['https://yourdomain.com', 'http://localhost:3000'];
    if (in_array($origin, $allowed, true)) {
        header("Access-Control-Allow-Origin: {$origin}");
        header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
        header('Access-Control-Allow-Headers: Content-Type, Authorization, x-wp-nonce');
        header('Access-Control-Allow-Credentials: true');
        header('Access-Control-Max-Age: 86400');
    }
    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
        status_header(204);
        exit;
    }
});

Note that **Access-Control-Allow-Origin: * and Allow-Credentials: true cannot coexist** (browser spec) — that's why I use an explicit origin whitelist instead of wildcard. After applying, verify with:

$ curl -I -X OPTIONS https://cms.example.com/graphql \
  -H "Origin: http://localhost:3000" \
  -H "Access-Control-Request-Headers: x-wp-nonce"
HTTP/2 204
access-control-allow-origin: http://localhost:3000
access-control-allow-headers: content-type, authorization, x-wp-nonce

Pitfall 2: Draft preview "looks like" it works but the frontend never picks up unpublished content

Symptom: Click "Preview" in the WordPress admin, the Next.js preview route accepts, but the frontend keeps showing the old version — it directly hits the ISR cache, ignoring draft updates.

Next.js's official Preview Mode documentation has a **detail not written in the docs** when mixed with ISR: ISR's revalidate is based on content hash, **it does not respect Next.js's preview cookie**. So even if generateStaticParams returns all slugs, draft previews forever hit the static page.

**Solution**: Switch the preview route from ISR to SSR, and inject the draft ID into the GraphQL query inside app/api/preview/route.ts:

// app/api/preview/route.ts
import { draftMode } from 'next/headers';
import { redirect } from 'next/navigation';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const slug = searchParams.get('slug');
  const token = searchParams.get('token');

  if (token !== process.env.PREVIEW_TOKEN) {
    return new Response('Invalid token', { status: 401 });
  }

  draftMode().enable();
  redirect(`/${slug}`);
}

// app/[slug]/page.tsx
import { draftMode } from 'next/headers';

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const { isEnabled: isDraft } = await draftMode();

  const post = await getPost(slug, { includeDraft: isDraft });
  // Inside getPost: when isDraft=true, add status: ['publish', 'draft'] to the query
  // ...
}

**Key point**: When fetching the GraphQL endpoint, you must pass { next: { revalidate: isDraft ? 0 : 3600 } } — preview mode sets revalidate to 0 to force SSR, production keeps 1-hour ISR. wp-graphql-smart-cache 2.2.1 automatically skips cache for drafts on the WP side (verified: draft state is fetched via GraphQL, automatically enters cache after publish).

Pitfall 3: ISR revalidate set to 3600 but posts take 2+ hours to update after publish

**Symptom**: All posts have revalidate: 3600 (1 hour), but in practice it takes 1 hour 47 minutes to update. I initially thought Next.js 16's ISR was acting up; after reading the source I realized — **WPGraphQL Smart Cache also caches the GraphQL response**, with a default 5-minute TTL.

That means the ISR static page is 1-hour cached, but the GraphQL response inside the ISR is from the WP-side cache, so the effective content delay = max(ISR revalidate, WPGraphQL Cache TTL) = max(3600s, 300s) = 3600s. That's correct, right?

Wrong. Next.js 16's ISR has a stale-while-revalidate behavior: the first request after expiration immediately returns the stale content (to guarantee TTFB) and regenerates in the background. If regeneration time exceeds the revalidate window, the next request still gets the stale content. This can cause 2-3 consecutive requests within 1 hour to all get stale content.

Solution:

1. On the WPGraphQL side, disable Smart Cache globally, or force-bypass per query field:

   // wp-config.php
   define('WP_GRAPHQL_SMART_CACHE_DISABLE', true);

Or use the no-cache directive in the GraphQL query (recommended for fine control):

   query GetPost($slug: ID!) {
     post(id: $slug, idType: SLUG) @cacheControl(maxAge: 0) {
       title content modified
     }
   }

2. **On the Next.js side**, use revalidateTag for on-demand revalidation (do not rely on timer):

   // app/api/revalidate/route.ts
   import { revalidateTag } from 'next/cache';
   import { headers } from 'next/headers';

   export async function POST(req: Request) {
     // Verify HMAC signature
     const sig = (await headers()).get('x-wp-signature');
     if (sig !== process.env.REVALIDATE_SECRET) return new Response('Forbidden', { status: 403 });

     const { slug, tag } = await req.json();
     revalidateTag(`post-${slug}`);
     return Response.json({ revalidated: true });
   }

Then on the WordPress side, use a WP Webhook (do_action('save_post', ...)) to call this endpoint, **ensuring updates within <5 seconds after publish**.

Verified: with revalidateTag + WPGraphQL cache disabled, the delay from WordPress save to Next.js frontend visibility stabilizes at 3-5 seconds (Vercel cold start + network), no longer 1-2 hours.

Pitfall 4: SEO metadata + OpenGraph completely lost, search engine index drops

**Symptom**: After going headless, Google Search Console's "Page not indexed" jumped from 5 to 23, and article titles completely disappeared from SERP. I initially suspected a Next.js 16 generateMetadata issue, but view-source showed the