Next.js WordPress App Router Example

This is the official Next.js 14 App Router example from the Vercel Next.js repository that uses WordPress as a headless CMS, demonstrating a full production-style frontend with draft preview, automatic sitemap generation, CMS-managed redirects, and on-demand cache revalidation.

What is the Next.js WordPress Example?

This template is a starter application, part of the Next.js examples collection, that wires a WordPress installation to a Next.js 14 App Router frontend through the WPGraphQL plugin. It accepts your WordPress URL and credentials as environment variables and outputs a fully typed, server-rendered website with pages, posts, SEO metadata from Yoast, a dynamic 404 page, robots.txt, and sitemap.xml. The official source lives under the canary branch of the vercel/next.js repository and is maintained by the Next.js team with community contributions.

Key Features

• Catch-all route ([[...slug]]) — Handles every WordPress page and post by asking GraphQL what content type a route represents, then rendering the matching template; removing this route breaks all page rendering.
• Auto-generated sitemap.ts — Pulls all paths from the WordPress REST endpoints and serves them as /sitemap.xml.
• robots.ts — Fetches the robots.txt content from the WordPress API and exposes it at /robots.txt.
• Redirect middleware — Reads stored redirects from the WordPress "Redirection" plugin and redirects users when a match is found; requires the WP_USER and WP_APP_PASS environment variables.
• CMS-editable 404 page — The not-found.tsx uses a configurable database ID to render a WordPress page whose slug is not-found, so editors can update 404 content without code changes.
• Draft and preview mode — Uses WPGraphQL JWT Authentication and Next.js Draft Mode so editors can preview drafts; draft posts without slugs are served from a /preview/{id} fake route.
• On-demand cache revalidation — All GraphQL requests are tagged wordpress; a bundled minimal WordPress theme calls /api/revalidate on post transitions to clear only the relevant cache tag.
• Automatic TypeScript types — codegen.ts generates types and a schema.gql file from the WordPress GraphQL schema on npm run dev, and an optional Apollo GraphQL VS Code extension config adds autocomplete.

Who is it for?

• Next.js developers building a headless WordPress site want a pre-wired App Router structure with typed GraphQL queries and folder conventions (app, components, gql, queries, utils).
• Agencies and freelancers delivering WordPress-powered sites need CMS-controlled redirects, SEO, and 404 pages without redeploying.
• Content teams need a preview/draft workflow where unpublished WordPress content is visible on the frontend before going live.

What can you do with the Next.js WordPress Example?

• Headless CMS builds: Use WordPress as the only content source while Next.js handles rendering, routing, and performance, with every entry type defined in the generated GraphQL schema.
• CMS-managed redirects: Install the Redirection plugin and manage all URL redirects from the WordPress admin instead of editing Next.js config.
• Custom page building with ACF: Pair Advanced Custom Fields PRO's Flexible Content with WPGraphQL for ACF to create a block-builder experience that outputs structured data instead of raw Gutenberg HTML.

How does the Next.js WordPress Example work?

Set up WordPress: set the site URL to the frontend, enable "Post name" permalinks, create a 404-not-found page, install required plugins (WPGraphQL, WPGraphQL SEO, WPGraphQL JWT Authentication, Redirection, Yoast SEO, optionally ACF Pro and WPGraphQL for ACF), enable introspection, and add four constants to wp-config.php. Then clone the repository, create a .env file with NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_WORDPRESS_API_URL, NEXT_PUBLIC_WORDPRESS_API_HOSTNAME, HEADLESS_SECRET, WP_USER, and WP_APP_PASS, and run npm run dev — type generation happens automatically.

FAQ

Is this example free to use?

Yes. It is an open-source example in the Next.js repository, released under the repository's license, and it relies on the free WordPress and WPGraphQL plugins. Optional paid tools like Advanced Custom Fields PRO are not required.

What WordPress plugins are required?

WPGraphQL, WPGraphQL SEO, Classic Editor, Redirection, Yoast SEO, and WPGraphQL JWT Authentication are listed as required; ACF Pro and WPGraphQL for ACF are marked optional but recommended for structured page building.

Can I customize the 404 page?

Yes. Create a WordPress page with slug 404-not-found, then change the database ID in not-found.tsx to match that page's post ID. The 404 content is then editable from the CMS.

Do I need to configure environment variables?

Yes. Six variables are needed: the frontend base URL, the WordPress API URL and hostname, a shared HEADLESS_SECRET, and a WordPress username/password (WP_USER and WP_APP_PASS) used for preview and redirects. Without the last two, preview mode and Redirection support will not work.