ForgeWP

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

Terminal
# 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 WordPress

2. Project Layout (What Every File Does)

Output
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> islands

3. 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 page entries inside cms/mock-data.ts AND also page files inside src/app/pages/? Which one creates my WordPress page?"

They do two completely different jobs — think of it as Design (Template) vs. Content (Database Record):

Table · 4 columns
Where it lives
What it represents
What happens in pnpm dev
What happens in WordPress after pnpm export
src/app/pages/About.tsx
The 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/ (using pnpm forgewp make:page AboutUs) and add it to src/app/routes.tsx for local preview.
  • Want realistic sample text/fields while designing locally (or starter content to seed on activation)? Add a matching slug entry under page: [...] in cms/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:

src/app/pages/About.tsx
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 from cms/mock-data.ts and cms/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:

src/app/page.tsx
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:

Terminal
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