ForgeWP

What ForgeWP Is

A plain-language introduction to ForgeWP, WordPress themes, React authoring, and the compiler model.

ForgeWP is a framework for authoring WordPress themes with React, Tailwind CSS 4, and Vite.

You write and preview your theme in a modern frontend project, then export it as a WordPress theme package. The exported theme uses PHP templates and compiler-generated HTML fragments; the compiler converts ForgeWP constructs it recognizes into WordPress behavior. React components are not all translated into PHP: ordinary components provide rendered markup, while recognized data, routing, and interactive-island features receive framework-specific output.

If you are new to programming, read this carefully:

ForgeWP lets you author a theme in a modern frontend environment and export files that WordPress can run. The compiler generates PHP integration and theme files for you. WordPress does not need Node.js to serve the site; client-side JavaScript is included when an interactive feature or generated block needs it.

The Problem ForgeWP Solves

WordPress themes can be built directly with PHP, native block templates, or visual builders. Those are valid approaches, and they can also use modern build tools. ForgeWP offers another workflow for developers who prefer React components and Tailwind CSS.

ForgeWP brings theme authoring, local mock content, WordPress bindings, block generation, and export into one development system. You can preview the design without a local database, then generate a theme that runs inside WordPress.

Build with ForgeWP's documented patterns, preview your design locally, and verify the exported theme in WordPress. This workflow covers both the frontend experience and the live content, plugins, and editing controls your clients will use.

The Core Packages

These packages provide the main authoring and export tools:

Table · 3 columns
Package
Role
Purpose
create-forgewp
Theme Scaffolder
The CLI tool that scaffolds a fresh, preconfigured ForgeWP theme project in seconds (npx create-forgewp).
@forgewp/compiler
Build Engine
The compiler that transforms React components into native WordPress PHP templates, theme.json, and Gutenberg blocks (pnpm forgewp export).
@forgewp/react
WordPress Primitives
Hooks and components that connect React markup to WordPress concepts, such as <WpImage />, <WpQueryLoop />, and <Hydrate />.
@forgewp/ui
Component Registry
Optional starter UI components that the forgewp add command can copy into a theme.

How ForgeWP Works: Mental Model

Think of ForgeWP as an artisan's workshop:

Flowchart
Rendering diagram...

  1. Development Mode (pnpm dev): ForgeWP operates like a Vite project. You edit components in TypeScript and preview them with fast refresh. You do not need a local WordPress server, Docker container, or MySQL database for the standard preview—the cms/ folder supplies mock content and settings. Some sample assets or optional integrations may still need network access.

  2. Compilation & Export (pnpm forgewp export): When you are ready to publish, the compiler builds assets, renders the app to HTML, converts recognized ForgeWP markers and constructs into PHP, generates WordPress theme files and theme.json, compiles registered Gutenberg blocks, and packages the result as a .zip archive.

Key Architectural Tenets

1. Static Output by Default

ForgeWP renders your React app during export and uses the resulting HTML in the theme. WordPress PHP provides the templates and connects recognized data features to live WordPress content. Interactive features can add client-side JavaScript, so the amount of JavaScript depends on the theme you build.

2. Selective Interactivity

Interactive components can be discovered and split into client-side islands by the compiler when their source matches supported patterns. Use <Hydrate> when you need to set a loading trigger or other hydration behavior explicitly. Keep browser-only work inside interactive components, and verify their behavior in the exported theme.

3. No Local Database Required

You can design and preview a theme without a running WordPress installation or database. The cms/ directory supplies local mock data; remote images, fonts, package installation, and optional integrations may still require an internet connection.

How ForgeWP Fits Your Workflow

ForgeWP combines developer-owned layouts with native WordPress content editing:

  • Layouts in source, content in WordPress: Author the design in React and expose the fields and Gutenberg blocks your clients need. WordPress saves their content and block attributes.
  • Native WordPress deployment: Export an installable theme that runs on the WordPress server. Your development machine or build runner handles the Node.js build tools.
  • Static rendering with focused interactivity: Generate PHP-backed templates and rendered markup, then add browser JavaScript through islands, blocks, and other enabled features.
Do I need Node.js or a specialized server to run my ForgeWP theme in production?

No. The ForgeWP compiler runs on your development machine or CI runner. The exported theme runs in WordPress without Node.js on the production server. It contains PHP, HTML, CSS, and, when needed, browser JavaScript; confirm the WordPress and PHP versions required by your target site and plugins before deployment.

Decide What the Client Can Edit

Before building a page, choose its editing model:

Table · 2 columns
Client needs to
Start with
Change a heading, image, or other named page value
defineEditable() and useWpMeta()
Write normal WordPress content inside a coded layout
<BlockArea />
Insert and reorder reusable page sections
Registered Gutenberg blocks on a content-rendering template
Compose smaller blocks inside a section
A parent block with innerBlocks

For example, a hotel can have a fixed room-page layout with editable room details, while its promotional pages use movable blocks. Use a single hero block for editing its text and image together, or nested blocks when editors should move those elements independently.

Continue to Content Ownership and Editability for the complete distinction, or Frequently Asked Questions for a comparison with other WordPress workflows.

Ready to dive in?

Continue to Who ForgeWP Is For to discover the recommended learning track for your background, or jump straight to Installation & First Theme to create your first theme.