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:
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/reactautomatically resolves to the client/SSR bundle. - In Next.js App Router Server Components, Turbopack/Webpack automatically resolves
@forgewp/reactto 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") renderspage.tsxandlayout.tsxas React Server Components (RSC) by default, where React hooks (useContext/useState) cannot run. Instead, Server Componentsawaitdata withcreateWpServerClient()and read editable schemas withgetWpEditable(schema, wp).
1. Entrypoints at a Glance
Import Path Used In What Lives Here @forgewp/reactBoth 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/nextNext.js next.config.{ts,mjs,js}withForgeWP(nextConfig, options) wrapper.@forgewp/react/configcms/*.{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-configwp.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.contentEmits <?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.slugVite: <?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 markupVite 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 clientVite compiles useWpTerms to get_terms() / get_the_terms().Dynamic Routes ( [slug])src/app/single.tsx + src/app/routes.tsxsrc/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 previewwp.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/linkIn 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, useWpSearchBuilt-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 pathsNext.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" componentsSame <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" componentsRespects prefers-reduced-motion across both adapters.Environment Checks isEditorPreview(), useIsEditorPreview(), isDecoupled(), useIsDecoupled(), isWordPress(), useIsWordPress()isNativeWordPressExport() + client hooks in "use client" componentsUse 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 4Generates 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 islandsBoth 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/reactNext.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(), WpBlockContextSame in "use client" / blocks; plain .map() in Server ComponentsPure JS utilities work everywhere. Internationalization (i18n) useWpI18n(), useWpLanguage() + cms/translations.{ts,js}cms/translations.{ts,js} + forgewp i18n:extract / i18n:translateSame .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)
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)
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.