Vite React Adapter
Author native WordPress themes with React 19, Vite, and Tailwind CSS — including how pages, cms/mock-data, hooks, and CLI commands fit together.
The Vite React adapter (frameworkAdapter: "react") is ForgeWP's default adapter. It gives you a fast Vite development server backed by local mock data in cms/, and compiles your React components into a standalone WordPress PHP theme ZIP with zero Node.js server required in production.
1. Quick Start
# TypeScript (default)
pnpm create forgewp my-theme
# Or JavaScript + JSX
pnpm create forgewp my-theme --js
cd my-theme
pnpm dev # Start local Vite preview (no WordPress database required)
pnpm export # Compile and package .forgewp/my-theme.zip for WordPress2. Project Layout (What Every File Does)
my-theme/
├── wp.config.ts # Theme name, slug, menus, CPTs, colors, fonts (or wp.config.js)
├── index.html # Local Vite HTML shell
├── cms/ # Local mock data for offline preview (and optional WP seeding)
│ ├── mock-data.ts # Sample posts, pages, and custom post types
│ ├── menus.ts # Sample navigation menus
│ ├── site-options.ts # Sample WordPress site options
│ └── forms/ # Native form schemas (defineWpForm)
└── src/
├── main.tsx # Local Vite entry point (or main.jsx)
├── app/
│ ├── layout.tsx # Shared header + footer chrome (compiles to header.php / footer.php)
│ ├── routes.tsx # Local Vite preview URL map (dev-only)
│ ├── page.tsx # Home page (compiles to front-page.php)
│ └── pages/ # Custom WordPress Page templates (e.g. About.tsx → page-about.php)
├── blocks/ # Gutenberg blocks (defineBlock + WpEditable)
└── components/ # UI components & interactive <Hydrate> islands3. Crucial Concept: cms/mock-data.ts Pages vs. src/app/pages/ Files
One of the most common questions for beginners in the Vite React adapter is:
"Why are there
pageentries insidecms/mock-data.tsAND also page files insidesrc/app/pages/? Which one creates my WordPress page?"
They do two completely different jobs — think of it as Design (Template) vs. Content (Database Record):
Where it lives What it represents What happens in pnpm devWhat happens in WordPress after pnpm exportsrc/app/pages/About.tsxThe Page Layout / Template (React JSX structure, sections, Tailwind styles, <BlockArea />, blocks)Rendered when you visit /about via src/app/routes.tsx.Compiles into page-about.php (a WordPress Page Template). On theme activation, ForgeWP auto-creates an empty WordPress Page stub tagged with _wp_page_template = 'page-about.php' and forgewp_route_id = 'about-page'.cms/mock-data.ts (page: [...])The Sample Content (page title, content HTML, excerpt, customFields)Supplies the fake text returned by useWpTitle(), useWpContent(), and useWpCustomField() so your local preview is not blank.Not shipped by default (WordPress uses real database pages). If you opt in with seed: { mockData: 'once' } (or 'upsert') in wp.config.ts, ForgeWP seeds those titles/content into the matching auto-created template stub via forgewp_route_id without creating duplicate pages or losing _wp_page_template. |
|---|
Rule of thumb:
- Want a new page design/URL? Create a component in
src/app/pages/(usingpnpm forgewp make:page AboutUs) and add it tosrc/app/routes.tsxfor local preview. - Want realistic sample text/fields while designing locally (or starter content to seed on activation)? Add a matching
slugentry underpage: [...]incms/mock-data.ts.
4. Reading WordPress Data in Vite React
In the Vite React adapter, all WordPress hooks and components are imported from @forgewp/react:
1import {
2 useWpTitle,
3 useWpContent,
4 useWpPageLink,
5 WpLink,
6 BlockArea,
7} from "@forgewp/react"
8
9export default function AboutPage() {
10 const title = useWpTitle("About Our Studio")
11 const content = useWpContent()
12 const contactUrl = useWpPageLink("contact-page", "/contact")
13
14 return (
15 <main className="mx-auto max-w-3xl px-6 py-12">
16 <h1>{title}</h1>
17 <BlockArea name="about-content" content={content} />
18 <WpLink href={contactUrl}>Get in touch</WpLink>
19 </main>
20 )
21}- In
pnpm dev, these hooks read fromcms/mock-data.tsandcms/menus.ts. - During
pnpm export, the compiler turns them into native WordPress PHP tags (get_the_title(),the_content(),forgewp_resolve_page_link()).
5. Interactive Components (<Hydrate>)
By default, Vite React exports zero client JavaScript for static pages. Whenever a component needs browser interactivity (React state, click handlers, carousels, modals, forms), wrap it in <Hydrate> or let ForgeWP's automatic hydration detector bundle only that island:
1import { Hydrate } from "@forgewp/react"
2import { NewsletterSignup } from "@/components/NewsletterSignup"
3
4export default function HomePage() {
5 return (
6 <main>
7 <h1>Welcome</h1>
8 <Hydrate trigger="visible">
9 <NewsletterSignup />
10 </Hydrate>
11 </main>
12 )
13}6. CLI Scaffolding Commands
All make:* commands work out of the box and automatically emit .tsx/.ts in TypeScript projects or .jsx/.js in JavaScript (--js) projects:
pnpm forgewp make:page AboutUs
pnpm forgewp make:block FeatureCard --attributes=heading,summary
pnpm forgewp make:island NewsletterSignup
pnpm forgewp make:form Contact
pnpm forgewp make:loop PortfolioGrid --postType=portfolio
pnpm forgewp make:shell SplitSection --layout=2-col
pnpm forgewp doctor