ForgeWP

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?

Table · 4 columns
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
# 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
1import { defineConfig } from "@forgewp/compiler/define-config"
2
3export default defineConfig({
4  configVersion: 1,
5  name: "My Theme",
6  slug: "my-theme",
7  version: "0.1.0",
8  description: "My WordPress theme built with ForgeWP.",
9  textDomain: "my-theme",
10  frameworkAdapter: "react", // "react" | "nextjs" | "html" | "./custom-adapter.js"
11})

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


Next Steps