ForgeWP

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:

  1. Native WordPress Theme Export (default): Compiles fixed App Router routes, shared layout chrome, verified next/link destinations, CSS, defineBlock Gutenberg blocks, <BlockArea /> slots, @forgewp/react/server live bindings, and explicit <Hydrate> client islands into a standalone WordPress theme ZIP with no Next.js server required.
  2. 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_id route mappings, and serialized forgewp_blocks.

1. Quick Start

Scaffold a new Next.js ForgeWP theme project with create-forgewp:

Terminal
pnpm create forgewp my-next-theme --adapter nextjs
cd my-next-theme
pnpm dev

When you are ready to build and package a native WordPress theme ZIP:

Terminal
pnpm export

pnpm 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:

Terminal
# 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:

Terminal
pnpm forgewp make:block FeatureCard --attributes=heading,summary
pnpm forgewp make:page ContactUs
pnpm forgewp make:island NewsletterSignup

2. 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):

next.config.ts
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 nextConfig

withForgeWP() configures three things automatically:

  • Boundary-selected output mode: Sets output: "export" by default for native WordPress extraction, and omits it when FORGEWP_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"] to config.resolve.extensionAlias so webpack builds (next dev --webpack, next build --webpack) resolve @forgewp/react cleanly with zero dynamic-dependency warnings.

In wp.config.ts, set frameworkAdapter: "nextjs":

wp.config.ts
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:

src/lib/content.ts
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:

Table · 3 columns
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-site
Fetches 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 in src/blocks/*.tsx (or scaffold with pnpm forgewp make:block). During native export, ForgeWP compiles them to blocks/<slug>/block.json, render.php, and assets/forgewp-editor.js wired to your packaged Next.js CSS (editorStyle).
  • Editable Regions (<BlockArea />): Import BlockArea from @forgewp/react/server in App Router Server Components (including the static front page) and pass content={page.content} for local/decoupled preview. Native export compiles <BlockArea /> to <?php the_content(); ?> inside WordPress post loop context.
  • Explicit Client Islands (<Hydrate>): Import Hydrate from @forgewp/react/server in 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 shared assets/islands/react-runtime.js module with esbuild, 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.

Table · 4 columns
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' islands
Supported
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-dynamic
Not 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.