# Vite React vs. Next.js API Reference


> A complete, beginner-friendly reference of every ForgeWP hook, component, and helper — and how each one works in Vite React vs. Next.js App Router.


If you are coming from the **Vite React** adapter and trying **Next.js App Router** (or vice versa), the good news is that **all shared ForgeWP components import from `@forgewp/react` identically in both adapters**:

```tsx
import {
  BlockArea,
  Hydrate,
  WpQueryLoop,
  WpMenu,
  WpRequireAuth,
  WpAuthGate,
  createWpServerClient,
  getWpEditable,
} from "@forgewp/react"
```

Under the hood, `@forgewp/react` uses the standard **`"react-server"` conditional export**:
- In **Vite React** (and Next.js `"use client"` components), `@forgewp/react` automatically resolves to the client/SSR bundle.
- In **Next.js App Router Server Components**, Turbopack/Webpack automatically resolves `@forgewp/react` to the server-safe implementation with zero client hooks.

The **one genuine difference** comes from React itself:
- **Vite React (`frameworkAdapter: "react"`)** renders every page as a regular React component tree, so you read post/page data with React hooks (`useWpTitle()`, `useWpMenu()`, `useWpQuery()`, `useWpMeta()`).
- **Next.js App Router (`frameworkAdapter: "nextjs"`)** renders `page.tsx` and `layout.tsx` as **React Server Components (RSC)** by default, where React hooks (`useContext`/`useState`) cannot run. Instead, Server Components `await` data with `createWpServerClient()` and read editable schemas with `getWpEditable(schema, wp)`.

---

## 1. Entrypoints at a Glance

| Import Path | Used In | What Lives Here |
| --- | --- | --- |
| `@forgewp/react` | **Both adapters** (Vite React everywhere, Next.js Server Components & `"use client"` islands) | **Unified components:** `<BlockArea />`, `<Hydrate />`, `<WpQueryLoop />`, `<WpMenu />`, `<WpRequireAuth />`, `<WpAuthGate />`. **Server data:** `createWpServerClient()`, `getWpEditable()`, `isNativeWordPressExport()`. **Client/Vite hooks:** `useWp*`, `defineBlock()`, `defineEditable()`, `useWpForm()`, `WpIcon`. |
| `@forgewp/react/next` | Next.js `next.config.{ts,mjs,js}` | `withForgeWP(nextConfig, options)` wrapper. |
| `@forgewp/react/config` | `cms/*.{ts,js}` and `wp.config.{ts,js}` (both adapters) | `defineWpForm()`, `definePageConfig()`, `defineWpPosts()`, `defineWpMenus()`, `defineWpUsers()`, `defineWpRoles()`, `defineTranslations()`, `defineWpThemeMods()`, `defineWpOptions()`, option field builders (`optionText`, `optionUrl`, `optionEmail`, `optionTextarea`, `optionToggle`, `optionNumber`, `optionPostPicker`). |
| `@forgewp/compiler/define-config` | `wp.config.{ts,js}` (both adapters) | `defineConfig()` with autocomplete and validation. |

---

## 2. Page & Post Content APIs

| Feature | Vite React (`@forgewp/react`) | Next.js App Router (`@forgewp/react`) | How It Compiles to WordPress |
| --- | --- | --- | --- |
| **Post / Page Title** | `useWpTitle(fallback?)` | `const page = await wp.getLivePage("home"); page.title` (or `wp.getLivePost(slug)`) | Vite: `<?php the_title(); ?>`. Next.js: PHP token / live REST field. |
| **Post / Page Body Content** | `useWpContent(fallback?)` or `<BlockArea />` | `<BlockArea name="main" content={page.content} />` or `page.content` | Emits `<?php the_content(); ?>` (or renders serialized Gutenberg blocks in decoupled mode). |
| **Excerpt** | `useWpExcerpt(fallback?)` | `post.excerpt` from `wp.getLivePost()` / `wp.getPosts()` | Vite: `<?php the_excerpt(); ?>`. Next.js: PHP loop / REST excerpt. |
| **Permalink / URL** | `useWpPermalink(fallback?)` | `post.permalink` / `post.slug` | Vite: `<?php the_permalink(); ?>`. Next.js: `get_permalink()` in `<WpQueryLoop />` or REST URL. |
| **Publish / Modified Date** | `useWpDate(format?)`, `useWpModifiedDate(format?)` | `post.date` from `wp.getLivePost()` / `wp.getPosts()` | Vite: `<?php echo get_the_date(); ?>`. Next.js: formatted date / PHP loop token. |
| **Author** | `useWpAuthor()` | `post.author` from `wp.getLivePost()` / `wp.getPosts()` | Vite: `<?php the_author(); ?>`. Next.js: author metadata / REST field. |
| **Featured Image** | `useWpFeaturedImage()` + `<WpImage />` | `post.featuredImage` + `next/image` (or `<img>`) | Vite: `get_the_post_thumbnail_url()`. Next.js: bundled theme asset or WordPress media URL. |
| **Custom Fields / Meta** | `useWpCustomField(key)`, `useWpField(key)`, `useWpMeta(key)` | `getWpEditable(schema, wp)` or `wp.getField(key)` | Vite: `get_post_meta(get_the_ID(), key, true)`. Next.js: `get_post_meta()` compile token / REST meta. |
| **Gutenberg Content Slot** | `<BlockArea />` | `<BlockArea />` | Identical WordPress output: renders the editable WordPress block content area (`the_content()`). |
| **Shortcodes** | `<WpShortcode code="[gallery]" />` | Native PHP shortcode output via `<BlockArea />` or server markup | Vite compiles `<WpShortcode />` to `echo do_shortcode(...)`. |

---

## 3. Queries, Loops, Taxonomies & Pagination

| Feature | Vite React (`@forgewp/react`) | Next.js App Router (`@forgewp/react`) | Notes |
| --- | --- | --- | --- |
| **Post / CPT / Product Loop** | `<WpQueryLoop postType="post" postsPerPage={6}>{(post) => ...}</WpQueryLoop>` | `<WpQueryLoop postType="post" postsPerPage={6} posts={posts}>{(post) => ...}</WpQueryLoop>` | Same `<WpQueryLoop />` component in both adapters; compiles directly to a native `WP_Query` PHP loop on export. |
| **Imperative Query** | `useWpQuery({ postType, perPage, category, ... })` | `await wp.getPosts("post", { perPage: 6 })` | Vite uses a React hook; Next.js uses an `async` call inside your Server Component. |
| **Prefetching Queries** | `useWpPrefetch()` | Built into Next.js App Router (`next/link` prefetch + `fetch` caching) | Next.js handles route prefetching automatically. |
| **Categories & Tags** | `useWpTerms(taxonomy)` and `useWpTaxonomyList()` | `post.categories` / `post.tags` or custom REST fetch via `wp` client | Vite compiles `useWpTerms` to `get_terms()` / `get_the_terms()`. |
| **Dynamic Routes (`[slug]`)** | `src/app/single.tsx` + `src/app/routes.tsx` | `src/app/posts/[slug]/page.tsx` + `generateStaticParams()` using `wp.getStaticParams("post")` | In Next.js native export, `[slug]/page.tsx` compiles to `single.php` (or `single-<cpt>.php`). |
| **Draft Previews** | Local `cms/mock-data.ts` preview | `wp.getLivePage(slug, { preview: true })` + Next.js `draftMode()` | Supports authenticated WordPress draft previews in decoupled mode. |

---

## 4. Navigation, Menus, Routing & Site Info

| Feature | Vite React (`@forgewp/react`) | Next.js App Router (`@forgewp/react` + `next/link`) | Notes |
| --- | --- | --- | --- |
| **Navigation Menus** | `<WpMenu location="primary" />` or `useWpMenu("primary")` | `<WpMenu location="primary" items={items} />` or `await wp.getMenu("primary")` | Same `<WpMenu />` component in both adapters; compiles to native WordPress `wp_get_nav_menu_items()` on export. |
| **Internal Links** | `<WpLink href={useWpPageLink("about-page", "/about")}>` | `<Link href="/about">` from `next/link` | In Next.js, ForgeWP automatically rewrites verified `next/link` destinations to live WordPress permalinks on export. |
| **Client Router** | `<Router>`, `<Route>`, `<Switch>`, `useLocation`, `useSearch`, `useParams`, `useRoute`, `useWpPagePath`, `useWpSearchParams`, `useWpLocation`, `useWpSearch` | Built-in Next.js App Router (`src/app/` folders, `searchParams` prop, `usePathname()`, `useSearchParams()` in `"use client"`) | You do **not** need `src/app/routes.tsx` in Next.js — folders define routes. |
| **Site Title, Tagline & Options** | `useWpOption("blogname")`, `useWpThemeMod("footer_text")` | `await wp.getSiteInfo()` / `wp.getOption("blogname")` | Both read from `cms/site-options.{ts,js}` locally and WordPress `get_option()` / REST in production. |
| **Theme Asset Paths** | `useWpThemeUri()`, `resolveWpAsset("/img/hero.jpg")` | `next/image` (automatically bundled into `assets/images/`) or `/public` paths | Next.js handles image and font bundling during `forgewp export`. |

---

## 5. Interactivity & Client Islands (`<Hydrate />`)

| Feature | Vite React (`@forgewp/react`) | Next.js App Router (`@forgewp/react`) | How It Works |
| --- | --- | --- | --- |
| **Client Islands** | `<Hydrate trigger="visible">` or auto-detected interactive components | `<Hydrate trigger="visible">` or auto-detected `"use client"` components | Same `<Hydrate />` component in both adapters; compiles interactive components into standalone JS island bundles (`load`, `visible`, `idle`, `interaction`). |
| **Reduced Motion** | `useReducedMotion()`, `getStaticMotionStyle()` | Same — import from `@forgewp/react` inside `"use client"` components | Respects `prefers-reduced-motion` across both adapters. |
| **Environment Checks** | `isEditorPreview()`, `useIsEditorPreview()`, `isDecoupled()`, `useIsDecoupled()`, `isWordPress()`, `useIsWordPress()` | `isNativeWordPressExport()` + client hooks in `"use client"` components | Use `isNativeWordPressExport()` in Next.js Server Components when you need to branch between static native export and live decoupled mode. |

---

## 6. Forms, Auth, SEO, Blocks & Shared Primitives

These APIs work with the **same WordPress backend contracts** in both adapters:

| Feature | Vite React | Next.js App Router | Notes |
| --- | --- | --- | --- |
| **Gutenberg Blocks** | `defineBlock()` from `@forgewp/react` + field builders (`text`, `richText`, `image`, `boolean`, `repeater`, `color`, `url`, `select`, `number`, `icon`) | **Identical** (`defineBlock()` from `@forgewp/react`) | Compiled into native `block.json` + Gutenberg editor JS + PHP `render.php` in both adapters. |
| **Editable Page Fields** | `defineEditable()`, `buildPageEditable()`, `pickEditable()`, `mergeEditable()`, `getEditableDefaults()`, `useWpMeta()` | `defineEditable()` + `getWpEditable(schema, wp)` in Server Components (or `useWpMeta()` in `"use client"`) | Lets clients edit named fields in WP Admin without breaking your layout. |
| **Theme Tokens (`theme.json`)** | `defineTheme()`, `<PresetsStyle />` | `wp.config.{ts,js}` design tokens + Tailwind CSS 4 | Generates WordPress `theme.json` color, font, and spacing presets. |
| **Native Forms** | `defineWpForm()` (`@forgewp/react/config`), `useWpForm()`, `submitWpForm()`, `<WpFormFields />`, `<WpFormSubmitButton />`, `useWpFormFieldLabels()` | `defineWpForm()` (`@forgewp/react/config`) + `useWpForm()` / `submitWpForm()` in `"use client"` form islands | Both submit to the exact same generated WordPress REST endpoint (`/wp-json/forgewp/v1/forms/<id>`). |
| **Authentication Guards** | `<WpRequireAuth />` & `<WpAuthGate />` from `@forgewp/react` (plus `@forgewp/auth` hooks) | `<WpRequireAuth />` & `<WpAuthGate />` from `@forgewp/react` (native PHP `is_user_logged_in()` / `current_user_can()` guards) | Identical component names from `@forgewp/react`; native export enforces auth at the PHP layer before HTML is even sent. |
| **SEO & Head Tags** | `<WpHead />`, `<SEO />` from `@forgewp/react` | Next.js `export const metadata` / `generateMetadata()` | On native export, ForgeWP hands `<title>` and meta tags cleanly to Yoast SEO / Rank Math / WordPress `wp_head()` when `seo.pluginHandoff` is enabled. |
| **Icons** | `<WpIcon />`, `registerIconProvider()`, `clearIconProviders()` | Same (`"use client"` or SVG icons) | Works identically in both adapters. |
| **Repeater & Utilities** | `<WpRepeater />`, `decodeHtmlEntities()`, `resolveDualHost()`, `WpBlockContext` | Same in `"use client"` / blocks; plain `.map()` in Server Components | Pure JS utilities work everywhere. |
| **Internationalization (i18n)** | `useWpI18n()`, `useWpLanguage()` + `cms/translations.{ts,js}` | `cms/translations.{ts,js}` + `forgewp i18n:extract` / `i18n:translate` | Same `.pot`/`.po` workflow in both adapters. |

---

## 7. Quick Side-by-Side Example

Here is the exact same "Latest Posts" page written in both adapters:

### Vite React (`src/app/pages/BlogPage.tsx`)

**src/app/pages/BlogPage.tsx**

```tsx
import { WpQueryLoop, WpLink } from "@forgewp/react"

export default function BlogPage() {
  return (
    <main className="mx-auto max-w-4xl py-16">
      <h1 className="text-4xl font-bold">Latest Articles</h1>
      <WpQueryLoop postType="post" postsPerPage={6} className="mt-8 grid gap-6 md:grid-cols-2">
        {(post) => (
          <article key={post.id} className="rounded-xl border p-6">
            <h2 className="text-xl font-semibold">
              <WpLink href={post.permalink}>{post.title}</WpLink>
            </h2>
            <p className="mt-2 text-zinc-600">{post.excerpt}</p>
          </article>
        )}
      </WpQueryLoop>
    </main>
  )
}
```

### Next.js App Router (`src/app/blog/page.tsx`)

**src/app/blog/page.tsx**

```tsx
import Link from "next/link"
import { WpQueryLoop } from "@forgewp/react"
import { wpClient } from "@/lib/content"

export default async function BlogPage() {
  const posts = await wpClient.getPosts("post", { perPage: 6 })

  return (
    <main className="mx-auto max-w-4xl py-16">
      <h1 className="text-4xl font-bold">Latest Articles</h1>
      <div className="mt-8 grid gap-6 md:grid-cols-2">
        <WpQueryLoop postType="post" useMainQuery={false} postsPerPage={6} posts={posts}>
          {(post) => (
            <article key={post.id} className="rounded-xl border p-6">
              <h2 className="text-xl font-semibold">
                <Link href={post.permalink}>{post.title}</Link>
              </h2>
              <p className="mt-2 text-zinc-600">{post.excerpt}</p>
            </article>
          )}
        </WpQueryLoop>
      </div>
    </main>
  )
}
```

Both use the **exact same `<WpQueryLoop />` component from `@forgewp/react`** and compile to a native WordPress PHP `WP_Query` template when you run `pnpm export`.

---

Source: [Vite React vs. Next.js API Reference](https://www.forgewp.dev/docs/core/adapters/api-differences)
