# 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**

```bash
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**

```bash
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**

```bash
# 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**

```bash
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**

```ts
import type { NextConfig } from "next"
import { withForgeWP } from "@forgewp/react/next"

const nextConfig: NextConfig = withForgeWP({
  // Your custom Next.js config options
})

export 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**

```ts
import { defineConfig } from "@forgewp/compiler/define-config"

export default defineConfig({
  configVersion: 1,
  name: "My Next Theme",
  slug: "my-next-theme",
  version: "0.1.0",
  description: "A WordPress theme built with Next.js App Router and ForgeWP.",
  textDomain: "my-next-theme",
  frameworkAdapter: "nextjs",
})
```

---

## 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**

```ts
import { createWpServerClient } from "@forgewp/react/server"
import { mockData } from "../../cms/mock-data"

export const wpClient = createWpServerClient({
  fixtures: mockData,
})

export async function getPageContent(slug: string) {
  return wpClient.getLivePage(slug)
}
```

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-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.

| 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. |

---

Source: [Next.js App Router Adapter](https://www.forgewp.dev/docs/core/compiler-engine/nextjs-adapter)
