# 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**

```bash
# 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)

```text
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)**:

| 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`. |

> [!TIP]
> **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**

```tsx
import {
  useWpTitle,
  useWpContent,
  useWpPageLink,
  WpLink,
  BlockArea,
} from "@forgewp/react"

export default function AboutPage() {
  const title = useWpTitle("About Our Studio")
  const content = useWpContent()
  const contactUrl = useWpPageLink("contact-page", "/contact")

  return (
    <main className="mx-auto max-w-3xl px-6 py-12">
      <h1>{title}</h1>
      <BlockArea name="about-content" content={content} />
      <WpLink href={contactUrl}>Get in touch</WpLink>
    </main>
  )
}
```

- 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**

```tsx
import { Hydrate } from "@forgewp/react"
import { NewsletterSignup } from "@/components/NewsletterSignup"

export default function HomePage() {
  return (
    <main>
      <h1>Welcome</h1>
      <Hydrate trigger="visible">
        <NewsletterSignup />
      </Hydrate>
    </main>
  )
}
```

---

## 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**

```bash
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
```

---

Source: [Vite React Adapter](https://www.forgewp.dev/docs/core/adapters/vite-react-adapter)
