ForgeWP

Classic, Hybrid, and Block Themes

Understand WordPress theme types, theme.json v3, and where ForgeWP's PHP-backed output fits.

WordPress supports more than one kind of theme. A classic theme uses PHP templates, a block theme uses HTML block templates for Full Site Editing (FSE), and a hybrid theme combines PHP templates with modern block-editor features such as theme.json.

ForgeWP currently exports a PHP-backed hybrid theme. The compiler renders React to HTML fragments, places those fragments into generated PHP templates, and writes theme.json for supported design settings. This is WordPress-native output, but it is not a full block theme with HTML templates that editors can rearrange in the Site Editor.

New to React or Modern Frontend?

If your background is classic PHP WordPress, read React Basics For Theme Authors alongside this guide. ForgeWP's React code is declarative and describes the markup that will appear in the generated theme.

Compare the Template Models

Classic and block themes use different template models. Both remain useful; a PHP template does not imply an outdated development workflow.

Classic vs. Block Themes
Classic Themes:
  - PHP template files (header.php, footer.php, index.php)
  - Procedural hook registration in functions.php
  - Optional fields, custom blocks, or page-builder integrations
  - Layout editing depends on the controls the theme exposes

Block Themes / Full Site Editing:
  - Pure HTML templates and modular block parts
  - Centralized design tokens in theme.json v3
  - Native Gutenberg Site Editor visual customization
  - High-performance CSS custom properties (variables)

Classic Themes

In a classic theme:

  • PHP files such as header.php, single.php, and footer.php define rendering.
  • WordPress hooks load assets and connect theme features to plugins and core.
  • Editors can use Gutenberg for post content. Fields, the Customizer, custom blocks, or a page builder can expose additional controls.
  • Developers maintain the PHP integration, often alongside modern JavaScript and CSS build tools.

Block Themes and Full Site Editing

With the release of Full Site Editing:

  • The entire website—from headers and navigation menus to footers and post grids—is constructed out of blocks.
  • Design tokens (colors, font sizes, spacing, container widths) are standardized into a single configuration file: theme.json.
  • Editors can use the native visual Site Editor (Appearance → Editor) to tweak styles, re-order sections, and adjust layouts without touching code.
  • Frontend asset size and performance still depend on the theme, blocks, plugins, and content.

Where ForgeWP Fits

ForgeWP's output is a hybrid theme: it uses generated PHP templates and static HTML fragments, alongside WordPress design settings and custom blocks. This distinction matters because theme.json support alone does not make a theme a block theme.

1. Modern Design Tokens via theme.json v3

Instead of injecting thousands of lines of unscoped CSS, ForgeWP compiles the color palettes, fonts, and container constraints defined in your wp.config.ts directly into WordPress theme.json presets.

WordPress automatically transforms these tokens into standard CSS custom properties:

  • var(--wp--preset--color--primary)
  • var(--wp--preset--font-size--large)
  • var(--wp--preset--spacing--50)

Both your React components and the WordPress Gutenberg block editor share the exact same design language and styling tokens.

2. Gutenberg Content and Design Settings

The generated theme includes theme.json settings and registers support for features such as wide alignment and responsive embeds. Editors can use Gutenberg in the post and page editor, and can insert custom ForgeWP blocks where the theme provides an editable content area. ForgeWP does not currently generate the HTML template files required for full Site Editor template editing.

3. Selective Hydration Islands

ForgeWP renders the initial page markup at export and keeps client-side JavaScript focused on interactive features. The compiler can discover eligible interactive components automatically; ForgeWP does not use React's or Next.js's 'use client' directive.

Inside theme.json v3

theme.json is the beating heart of a modern WordPress Block Theme. It acts as both a design system schema and a permissions manifest.

Below is an example of the production theme.json v3 file automatically generated by ForgeWP during pnpm export:

theme.json
1{
2  "$schema": "https://schemas.wp.org/trunk/theme.json",
3  "version": 3,
4  "settings": {
5    "appearanceTools": true,
6    "layout": {
7      "contentSize": "1280px",
8      "wideSize": "1536px"
9    },
10    "color": {
11      "palette": [
12        {
13          "slug": "primary",
14          "color": "#0ea5e9",
15          "name": "Primary"
16        },
17        {
18          "slug": "background",
19          "color": "#090d16",
20          "name": "Background"
21        }
22      ]
23    },
24    "typography": {
25      "fontFamilies": [
26        {
27          "fontFamily": "Inter, sans-serif",
28          "slug": "inter",
29          "name": "Inter"
30        }
31      ]
32    }
33  }
34}

Key Properties Explained

  • $schema: Points to the official WordPress JSON schema, enabling autocomplete and instant validation in modern code editors.
  • version: 3: The theme.json schema version supported by WordPress 6.6 and newer.
  • appearanceTools: true: Unlocks advanced controls in the WordPress Block Editor (padding, margin, border radius, and typography settings).
  • layout.contentSize & layout.wideSize: Sets the default reading container width and wide container width, matching Tailwind CSS container utility rules.
  • color.palette: Exposes your brand colors inside the WordPress block color pickers.
Automated by ForgeWP

You do not need to write or maintain theme.json by hand. ForgeWP automatically derives these settings from your wp.config.ts configuration during export.

Architectural Comparison

Table · 3 columns
Dimension
Classic WordPress Theme
ForgeWP Hybrid Theme
Source Language
PHP, HTML, CSS
TypeScript, React, TSX, and Tailwind CSS
Generated Theme
PHP templates and styles
PHP templates, rendered HTML fragments, assets, and theme.json
Component Model
PHP template parts (get_template_part())
React components and optional compiled Gutenberg blocks
Interactivity
Theme JavaScript and plugins
Browser JavaScript for discovered or explicit hydration islands
Local Development
Usually requires a PHP/WordPress installation
Vite preview can use local CMS mock data without a database
Editor Integration
Depends on theme features
Gutenberg content editing, registered blocks, and theme.json settings
Build Pipeline
Varies by theme
Vite build and ForgeWP export pipeline

Write React; ForgeWP Generates PHP

For typical theme layouts, you author the UI in React and let ForgeWP generate the WordPress PHP integration:

The Zero-PHP Developer Experience
What You Write (Modern Frontend):
  ├── React components (TSX)
  ├── TypeScript interfaces and types
  └── Tailwind CSS 4 utility classes

What ForgeWP Generates (Native WordPress):
  ├── Valid theme.json v3 configuration
  ├── PHP templates and rendered HTML fragments
  ├── Preloaded, optimized static assets
  └── Standard WordPress .zip distribution

You usually do not need to write the generated theme's PHP templates yourself. The exported files are still PHP, and advanced projects may add server-side PHP integrations.

Does `theme.json` make a ForgeWP theme a full block theme?

No. theme.json provides design settings to WordPress, but a full block theme also needs block template files. ForgeWP currently generates PHP-backed templates. Editors can still work with Gutenberg content and the theme's registered blocks; see Design Tokens & theme.json v3 for the settings ForgeWP exports.

Next Step: The Content Model

Proceed to The WordPress Content Model to understand how WordPress structures posts, pages, custom post types, and post metadata.