ForgeWP

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
1import {
2  BlockArea,
3  Hydrate,
4  WpQueryLoop,
5  WpMenu,
6  WpRequireAuth,
7  WpAuthGate,
8  createWpServerClient,
9  getWpEditable,
10} 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

Table · 3 columns
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

Table · 4 columns
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

Table · 4 columns
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

Table · 4 columns
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 />)

Table · 4 columns
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:

Table · 4 columns
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
1import { WpQueryLoop, WpLink } from "@forgewp/react"
2
3export default function BlogPage() {
4  return (
5    <main className="mx-auto max-w-4xl py-16">
6      <h1 className="text-4xl font-bold">Latest Articles</h1>
7      <WpQueryLoop postType="post" postsPerPage={6} className="mt-8 grid gap-6 md:grid-cols-2">
8        {(post) => (
9          <article key={post.id} className="rounded-xl border p-6">
10            <h2 className="text-xl font-semibold">
11              <WpLink href={post.permalink}>{post.title}</WpLink>
12            </h2>
13            <p className="mt-2 text-zinc-600">{post.excerpt}</p>
14          </article>
15        )}
16      </WpQueryLoop>
17    </main>
18  )
19}

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

src/app/blog/page.tsx
1import Link from "next/link"
2import { WpQueryLoop } from "@forgewp/react"
3import { wpClient } from "@/lib/content"
4
5export default async function BlogPage() {
6  const posts = await wpClient.getPosts("post", { perPage: 6 })
7
8  return (
9    <main className="mx-auto max-w-4xl py-16">
10      <h1 className="text-4xl font-bold">Latest Articles</h1>
11      <div className="mt-8 grid gap-6 md:grid-cols-2">
12        <WpQueryLoop postType="post" useMainQuery={false} postsPerPage={6} posts={posts}>
13          {(post) => (
14            <article key={post.id} className="rounded-xl border p-6">
15              <h2 className="text-xl font-semibold">
16                <Link href={post.permalink}>{post.title}</Link>
17              </h2>
18              <p className="mt-2 text-zinc-600">{post.excerpt}</p>
19            </article>
20          )}
21        </WpQueryLoop>
22      </div>
23    </main>
24  )
25}

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.