ForgeWP was created to make WordPress theme authoring accessible, fast, and enjoyable for developers coming from varied backgrounds. Whether you have never touched WordPress before or have been building PHP themes for a decade, there is a clear path forward for you.

Prerequisites: What You Need to Get Started

Before you start, make sure your development environment has the following tools installed:

Choose Your Learning Track

Select the pathway below that best matches your current experience:

Track 1: If You Are a React / Frontend Developer

You already understand components, props, hooks, JSX, and Tailwind CSS. Your focus will be on understanding how WordPress structures content.

• What will feel familiar: Writing .tsx files, instant Hot Module Replacement (HMR), component composition, and Tailwind styling.
• What you need to learn:
  • The Template Hierarchy: How WordPress routes different URLs to templates like index.php, single.php, page.php, and archive.php (see The Template Hierarchy Demystified).
  • WordPress Data Model: How post types, custom fields (ACF), menus, and media attachments work (see The WordPress Content Model).
  • The <WpQueryLoop> Primitive: How to fetch and iterate over posts declaratively so the compiler can generate native WordPress queries (see Loops, Custom Post Types & Queries).
  • Gutenberg Blocks: How to author React components that register as native WordPress editor blocks via pnpm forgewp make:block (see Create A Gutenberg Block).

Track 2: If You Are a WordPress / PHP Developer

You already understand the WordPress template hierarchy, functions.php, theme.json, hooks, and the WordPress admin dashboard. Your focus will be on learning modern component-based UI authoring.

• What will feel familiar: The concept of theme templates, template parts, and WordPress data concepts.
• What you need to learn:
  • Component Composition: Breaking monolithic PHP templates into modular, reusable .tsx components (see Components, Props & JSX for Themes).
  • Tailwind CSS 4: Replacing scattered CSS files and stylesheets with utility classes applied directly in your JSX markup (see Styling with Tailwind CSS 4).
  • The Build & Export Step: Instead of editing live PHP on the server, you author your theme in src/app and run pnpm forgewp export to generate the production theme (see Export A WordPress Theme).

Track 3: If You Are Building Themes for Clients & Agencies

If you deliver custom themes to clients, evaluate ForgeWP for its React authoring workflow and explicit editing boundaries. Development speed and handoff quality depend on the project and the controls you build.

• Local prototyping: Use mock data in cms/mock-data.ts to preview layouts without a running WordPress database. Test the export on WordPress before handoff.
• Theme delivery: Export a WordPress theme ZIP. The production server does not need Node.js; check the host's WordPress/PHP versions and the project's plugin requirements.
• Client editing: Expose menus, fields, content slots, and reusable blocks deliberately. Clients edit those values and compositions in WordPress, while developers maintain the surrounding JSX layouts.

Track 4: If You Are New to Programming

If you are just beginning your programming journey, welcome!

• Start simple: Focus first on running the dev server (pnpm dev), editing plain text inside components in src/app/page.tsx, and watching the browser update in real time.
• Take it step by step: You do not need to understand compiler abstract syntax trees (ASTs) or PHP transpilation to build a beautiful website. The framework handles the conversion for you.

Recommended Reading Order

To get the most out of this documentation, we recommend progressing through the sections in this sequence:

• Getting Started: Learn the framework's mental model and vocabulary.
• Installation & First Theme: Check requirements, scaffold a project, preview it, and export it.
• Project Anatomy: Find the source, CMS mock data, configuration, and generated output.
• WordPress Basics: Learn WordPress content types and how WordPress chooses templates.
• React Basics For Theme Authors: Learn JSX, component composition, and React state.
• Styling & Design System: Connect theme settings, Tailwind CSS, and Gutenberg content styles.
• WordPress Data Layer: Read posts, query collections, render menus, and access settings.
• Assets, Images & Media Handling: Use <WpImage />, theme assets, and the build-time WebP pipeline.
• Components & Registry: Add editable UI source and compose it with WordPress primitives.
• Continue with Gutenberg Blocks, then explore the later feature guides.