# Choosing a Framework Adapter


> Understand what ForgeWP framework adapters do, compare Vite React, Next.js App Router, and Static HTML, and pick the right one for your project.


A **framework adapter** tells ForgeWP how to build, preview, and compile your frontend codebase into a WordPress theme.

Every adapter shares the same WordPress engine under the hood (`@forgewp/compiler`): PHP template generation, Gutenberg blocks (`defineBlock`), `theme.json`, Sharp image optimization, Native Forms, SEO plugin handoff, Auth guards, and WooCommerce REST endpoints. What changes is the **frontend authoring environment** you write your pages and components in.

---

## Which Adapter Should I Pick?

| Adapter | Best For | Deployment Modes | Language Support |
| :--- | :--- | :--- | :--- |
| **Vite React (`react`)** *(default)* | Fast, lightweight WordPress themes with zero framework overhead, rich Gutenberg blocks, and selective client hydration. | Native WordPress theme ZIP | TypeScript (`.ts`/`.tsx`) & JavaScript (`.js`/`.jsx`) |
| **Next.js App Router (`nextjs`)** | Teams who already know Next.js App Router (`src/app/`), `next/link`, `next/image`, `next/font`, or want to run **either** a native WordPress theme ZIP **or** a decoupled Next.js frontend from one codebase. | Native WordPress theme ZIP **or** Decoupled Next.js server | TypeScript (`.ts`/`.tsx`) & JavaScript (`.js`/`.jsx`) |
| **Static HTML (`html`)** | Ultra-simple static landing pages or converting an existing HTML/CSS/JS site into a WordPress theme without React. | Native WordPress theme ZIP | HTML, CSS, JavaScript |

---

## Scaffolding With Your Chosen Adapter

Pass `--adapter` (and optionally `--js` if you prefer JavaScript over TypeScript) to `create-forgewp`:

**Terminal**

```bash
# 1. Vite React (default) — TypeScript or JavaScript
pnpm create forgewp my-theme
pnpm create forgewp my-theme --js

# 2. Next.js App Router — TypeScript or JavaScript
pnpm create forgewp my-next-theme --adapter nextjs
pnpm create forgewp my-next-theme --adapter nextjs --js

# 3. Static HTML
pnpm create forgewp my-html-theme --adapter html
```

You can also run `pnpm create forgewp` with no flags to choose the adapter and language interactively.

---

## How ForgeWP Knows Which Adapter to Use

Every ForgeWP project has a `wp.config.ts` (or `wp.config.js` / `wp.config.mjs`) file in the project root. The `frameworkAdapter` field tells the compiler which adapter to load:

**wp.config.ts**

```ts
import { defineConfig } from "@forgewp/compiler/define-config"

export default defineConfig({
  configVersion: 1,
  name: "My Theme",
  slug: "my-theme",
  version: "0.1.0",
  description: "My WordPress theme built with ForgeWP.",
  textDomain: "my-theme",
  frameworkAdapter: "react", // "react" | "nextjs" | "html" | "./custom-adapter.js"
})
```

If you omit `frameworkAdapter`, ForgeWP defaults to `"react"` (the Vite React adapter).

---

## Next Steps

- Using the default React + Vite setup? Read the [Vite React Adapter Guide](https://www.forgewp.dev/docs/adapters/vite-react/vite-react-adapter).
- Using Next.js App Router? Read the [Next.js App Router Adapter Guide](https://www.forgewp.dev/docs/adapters/nextjs/nextjs-adapter).
- Want to see exactly how every hook and component behaves in Vite React vs. Next.js? Read the [Vite React vs. Next.js API Reference](https://www.forgewp.dev/docs/adapters/reference/api-differences).
- Building with plain HTML or writing your own adapter? Read [Static HTML & Custom Adapters](https://www.forgewp.dev/docs/adapters/other-adapters/html-and-custom-adapters).

---

Source: [Choosing a Framework Adapter](https://www.forgewp.dev/docs/core/adapters/overview)
