Next.js App Router Adapter
Author WordPress themes with ordinary Next.js App Router code, export fixed routes into native WordPress themes, or deploy decoupled against the same WordPress content model.
The nextjs adapter lets you author pages, layouts, CSS, and Gutenberg blocks in a standard Next.js App Router project (src/app/) and target two deployment modes from the same codebase:
- Native WordPress Theme Export (default): Compiles fixed App Router routes, shared layout chrome, verified
next/linkdestinations, CSS,defineBlockGutenberg blocks,<BlockArea />slots,@forgewp/react/serverlive bindings, and explicit<Hydrate>client islands into a standalone WordPress theme ZIP with no Next.js server required. - Decoupled Next.js Frontend: Runs the same App Router application as a live Next.js server (
FORGEWP_DEPLOYMENT_MODE=decoupled+FORGEWP_WP_URL=https://your-wp-site) reading live WordPress REST content,forgewp_route_idroute mappings, and serializedforgewp_blocks.
1. Quick Start
Scaffold a new Next.js ForgeWP theme project with create-forgewp:
pnpm create forgewp my-next-theme --adapter nextjs
cd my-next-theme
pnpm devWhen you are ready to build and package a native WordPress theme ZIP:
pnpm exportpnpm export runs forgewp export, loads wp.config.ts (frameworkAdapter: "nextjs"), builds your Next.js app with FORGEWP_NATIVE_EXPORT=1, compiles Gutenberg blocks and explicit <Hydrate> islands, validates the generated theme strictly, and writes .forgewp/<slug>.zip.
Onboarding an Existing Next.js App (forgewp init)
If you already have a Next.js App Router codebase, run forgewp init to audit native vs. decoupled compatibility upfront and wire ForgeWP non-destructively:
# Preview compatibility report and planned file changes without writing
pnpm forgewp init --dry-run
# Wrap next.config.* with withForgeWP(), create wp.config.ts, cms/mock-data.ts, src/lib/content.ts, and .env.example
pnpm forgewp init- Marketing / static Next.js repos without request-time server APIs are marked ready for native WordPress theme export.
- Full-stack Next.js repos (e.g. using
middleware.ts,route.ts, Server Actions, Prisma/Supabase, or[slug]routes) receive an upfront recommendation to use decoupled mode (pnpm dev:decoupled+FORGEWP_WP_URL) rather than attempting native PHP export.
You can re-run pnpm forgewp doctor anytime to verify withForgeWP(), native compatibility, and exported island chunks, or scaffold new Next.js files directly:
pnpm forgewp make:block FeatureCard --attributes=heading,summary
pnpm forgewp make:page ContactUs
pnpm forgewp make:island NewsletterSignup2. Configuration (next.config.ts & wp.config.ts)
Wrap your Next.js configuration with withForgeWP() from @forgewp/react/next (also re-exported from @forgewp/react/config):
1import type { NextConfig } from "next"
2import { withForgeWP } from "@forgewp/react/next"
3
4const nextConfig: NextConfig = withForgeWP({
5 // Your custom Next.js config options
6})
7
8export default nextConfigwithForgeWP() configures three things automatically:
- Boundary-selected output mode: Sets
output: "export"by default for native WordPress extraction, and omits it whenFORGEWP_DEPLOYMENT_MODE=decoupled(or{ deploymentMode: "decoupled" }) is active. transpilePackages: Includes@forgewp/react(merged with any packages you declare).- Webpack TypeScript extension resolution: Adds
.js→[".ts", ".tsx", ".js"]and.jsx→[".tsx", ".jsx"]toconfig.resolve.extensionAliasso webpack builds (next dev --webpack,next build --webpack) resolve@forgewp/reactcleanly with zero dynamic-dependency warnings.
In wp.config.ts, set frameworkAdapter: "nextjs":
1import { defineConfig } from "@forgewp/compiler/define-config"
2
3export default defineConfig({
4 configVersion: 1,
5 name: "My Next Theme",
6 slug: "my-next-theme",
7 version: "0.1.0",
8 description: "A WordPress theme built with Next.js App Router and ForgeWP.",
9 textDomain: "my-next-theme",
10 frameworkAdapter: "nextjs",
11})3. Unified Server Component Data (@forgewp/react/server)
Use createWpServerClient() in Next.js Server Components to keep one data-loading boundary across local development, decoupled WordPress, and native WordPress export:
1import { createWpServerClient } from "@forgewp/react/server"
2import { mockData } from "../../cms/mock-data"
3
4export const wpClient = createWpServerClient({
5 fixtures: mockData,
6})
7
8export async function getPageContent(slug: string) {
9 return wpClient.getLivePage(slug)
10}How wpClient resolves data in each mode:
Mode Trigger Behavior Local Development Default (no FORGEWP_WP_URL, no FORGEWP_NATIVE_EXPORT)Reads typed fixtures from cms/mock-data.ts (defineWpPosts).Decoupled WordPress FORGEWP_WP_URL=https://your-wp-siteFetches live WordPress REST content, forgewp_route_id route permalinks (/wp-json/forgewp/v1/routes), and forgewp_blocks.Native WordPress Export FORGEWP_NATIVE_EXPORT=1 (set automatically during forgewp export)Emits ForgeWP compile tokens ( __FORGEWP_THE_TITLE__, __FORGEWP_THE_CONTENT__, __FORGEWP_META_*__, __FORGEWP_OPTION_*__) that compile to native WordPress PHP template tags. |
|---|
4. Client Interactivity & Gutenberg Blocks
- Gutenberg Blocks (
defineBlock+WpEditable): Place blocks insrc/blocks/*.tsx(or scaffold withpnpm forgewp make:block). During native export, ForgeWP compiles them toblocks/<slug>/block.json,render.php, andassets/forgewp-editor.jswired to your packaged Next.js CSS (editorStyle). - Editable Regions (
<BlockArea />): ImportBlockAreafrom@forgewp/react/serverin App Router Server Components (including the static front page) and passcontent={page.content}for local/decoupled preview. Native export compiles<BlockArea />to<?php the_content(); ?>inside WordPress post loop context. - Explicit Client Islands (
<Hydrate>): ImportHydratefrom@forgewp/react/serverin Server Components and wrap interactive'use client'components (e.g.<Hydrate id="counter-island"><CounterIsland /></Hydrate>) when they must run in the browser inside a native WordPress theme. The Next.js adapter bundles explicit islands and a sharedassets/islands/react-runtime.jsmodule withesbuild, without shipping_next/static/chunks/*, and rejects server-only imports (server-only,next/headers,next/cookies,next/cache) inside hydrated islands. Pages without<Hydrate>ship zero client JavaScript in native WordPress themes.
5. Compatibility Matrix
Native WordPress export intentionally targets fixed-route App Router sites and fails loudly with actionable NEXT_NATIVE_* diagnostics when a project uses features that require a request-time Next.js server runtime.
Feature / API Native WordPress Export Decoupled Next.js Mode Notes Fixed App Router pages ( /, /about, nested static routes, 404)Supported Supported Shared leading <header> and trailing <footer> are extracted into header.php / footer.php.Global & CSS Module stylesheets Supported Supported Packaged into assets/ and enqueued via wp_enqueue_style; _next/ runtime chunks are stripped.next/link (static string, template, or { pathname, query, hash })Supported Supported Rewritten via AST scope analysis to forgewp_resolve_route_url() so wp-admin slug renames work without rebuilding. Dynamic href expressions fail with NEXT_LINK_DYNAMIC_HREF.@forgewp/react/server (createWpServerClient)Supported Supported Switches cleanly between cms/mock-data.ts, WordPress REST, and native PHP compile tokens.defineBlock, WpEditable, <BlockArea />Supported Supported Live Gutenberg edits reflect without rebuilding in both modes. Explicit <Hydrate> 'use client' islandsSupported Supported Bundled via esbuild into assets/islands/*; server-only imports are blocked.Dynamic route segments ( [slug], [...slug])Not yet supported ( NEXT_NATIVE_DYNAMIC_ROUTE)Supported Planned as a follow-up mapping to WordPress single.php / archive.php.Route Handlers ( route.ts), Middleware (middleware.ts / proxy.ts), Server Actions ("use server"), next/headers, force-dynamicNot supported ( NEXT_NATIVE_* error)Supported Require a request-time Next.js server; use WordPress REST or src/server/*.php for native themes.ISR ( export const revalidate = N)Warning ( NEXT_NATIVE_ISR_REVALIDATE)Supported Native WordPress PHP templates read live from WordPress directly. Turbopack ( next build --turbopack)Not yet verified Not yet verified Use the verified webpack scripts ( next dev --webpack, next build --webpack) provided by create-forgewp.Optional ForgeWP modules (Auth, Forms, SEO, WooCommerce) Not yet audited for Next.js parity Not yet audited for Next.js parity Currently verified on the Vite React adapter. |
|---|