ForgeWP

Monorepo & Package Architecture

Internal architecture of the ForgeWP monorepo, package responsibilities, cross-package linking, and build pipelines.

The ForgeWP framework is architected as a modular monorepo managed with PNPM workspaces. The repository separates compiler tooling, the isomorphic React runtime, UI component registries, theme templates, and scaffolding utilities into distinct, decoupled packages.

This architecture enables developers to contribute enhancements to the compiler, add new React hooks, expand the UI registry, or create new framework adapters with immediate Hot Module Replacement (HMR) across the testbed theme.

Flowchart
Rendering diagram...

1. Monorepo Structure

The monorepo root configures workspace packages in pnpm-workspace.yaml:

pnpm-workspace.yaml
1packages:
2  - "packages/*"

Directory Anatomy

Table · 3 columns
Path
Package Name
Responsibility
packages/compiler/
@forgewp/compiler
AST parsing, Vite build plugins, SSR render engine (render-theme.mts), asset orchestrator (Sharp/WOFF2), and the 25 canonical forgewp command keys.
packages/react/
@forgewp/react
Zero-dependency isomorphic runtime, WordPress data hooks (useWpTitle, useWpQuery), primitives (<WpImage>, <WpQueryLoop>), and schema definitions (defineBlock, defineEditable).
packages/ui/
@forgewp/ui
Accessible UI component registry consumed by pnpm forgewp add <component>.
packages/create-forgewp/
create-forgewp
Interactive scaffolding CLI published to npm as npm create forgewp@latest.
packages/starter/
starter
The canonical React starter theme template and active development testbed.
packages/html-starter/
html-starter
Vanilla HTML framework adapter template.
packages/auth/
@forgewp/auth
Frontend and REST authentication, registration, session management, and verification emails.
packages/woocommerce/
@forgewp/woocommerce
WooCommerce storefront data bridge, cart management, and product loop primitives.
packages/plugin-seo/
@forgewp/plugin-seo
First-party compiler plugin for metadata injection and social share cards.
scripts/
Internal Tooling
Template sync scripts (sync-cli-template.mjs), workspace runner (run-workspace.mjs), and WordPress sync utilities.

2. Core Package Responsibilities

@forgewp/compiler

The engine of ForgeWP. Located in packages/compiler/, it handles the complete translation from modern web code to WordPress theme output:

  • CLI Commands (bin/): Implements forgewp export, doctor, repair, clean, fresh, add, make:*, sync:*, seed, and i18n:*.
  • AST Parser & Transpiler (lib/): Shared Babel parser that converts JSX loops (<WpQueryLoop>) into native PHP WP_Query loops, transpiles Gutenberg block definitions into block.json manifests, and extracts hydration islands.
  • Node SSR Engine (lib/render-theme.mts): Executes React components inside Node.js to capture initial server markup while polyfilling browser environments.
  • Asset Pipeline (lib/build-assets.js, lib/asset-loader.js): Bundles client JavaScript chunks, converts raster images to responsive WebP with Sharp, and downloads Google Fonts to local .woff2 files.
  • Theme Generator (lib/generate-theme.js): Emits style.css, theme.json v3, functions.php, and WordPress template hierarchy files (index.php, single.php, archive.php).

@forgewp/react

The isomorphic client library. Located in packages/react/, it provides the declarative React APIs used by theme authors:

  • Zero Client Overhead: Primitives like <WpQueryLoop>, <WpMenu>, and data hooks (useWpTitle(), useWpDate()) are purely compile-time constructs that emit PHP code during export and return mock data during local development.
  • Context System (src/context.ts): Manages WpPostContext and WpBlockContext for providing contextual post data across component trees.
  • Schema Builders (src/config.ts, src/hooks.ts): Defines defineBlock(), defineEditable(), field helpers (text(), richText(), image(), repeater()), and blueprint seeding helpers (defineWpPosts(), defineWpMenus(), defineWpOptions()).

@forgewp/ui

The component registry. Located in packages/ui/, it houses accessible UI primitives (buttons, modals, dropdowns, sheet drawers, tabs):

  • Components are built using Tailwind CSS and Radix UI primitives.
  • Supports dual styling modes: shadcn (rounded borders) and forgewp (sharp, geometric aesthetic).
  • Distributed via copy-paste scaffolding through pnpm forgewp add <name>, giving theme authors full ownership of component source code.

create-forgewp

The project scaffolder. Located in packages/create-forgewp/:

  • Ships with embedded starter templates in packages/create-forgewp/template/ (React) and template-html/ (Vanilla HTML).
  • Detects the active package manager (pnpm, npm, yarn, bun) and monorepo workspace configurations.
  • Configures Tailwind CSS 4, TypeScript, and initial WordPress blueprints.

3. Cross-Package Linking & Workspaces

The monorepo uses PNPM workspace protocol references (workspace:*). This links framework packages locally without publishing to npm:

packages/starter/package.json
1{
2  "dependencies": {
3    "@forgewp/react": "workspace:*",
4    "@forgewp/compiler": "workspace:*"
5  }
6}

Live Workspace Development

When you run pnpm dev at the monorepo root, the script runner delegates execution to packages/starter:

  1. Any code changes made inside packages/react/src/ or packages/compiler/lib/ are immediately picked up by the Vite dev server running in packages/starter.
  2. Vite Hot Module Replacement (HMR) updates the browser instantly without requiring manual rebuilding or relinking of packages.

4. Monorepo Scripts Reference

The root package.json provides unified commands that orchestrate tasks across the monorepo:

Table · 2 columns
Command
Action
pnpm dev
Starts the local development server in packages/starter with live reload.
pnpm build
Executes production compilation across all workspace packages.
pnpm typecheck
Runs TypeScript type checking across the entire monorepo (tsc --noEmit).
pnpm export
Runs the production theme export pipeline in packages/starter, producing .forgewp/out/.
pnpm preview
Previews the compiled production build locally.
pnpm sync:template
Synchronizes files from packages/starter into packages/create-forgewp/template.
pnpm sync:template-html
Synchronizes files into packages/create-forgewp/template-html.
pnpm test:compiler-adapters
Runs runtime and typing test suites for compiler framework adapters.
pnpm test:create
Tests the create-forgewp interactive scaffolding process.
pnpm test:create-html
Tests non-interactive HTML adapter project scaffolding.

Next Steps

Now that you understand the monorepo architecture and package contracts, proceed to the Contribution Guidelines & Testing to set up your local development environment, run test suites, and submit pull requests.