ForgeWP

Framework Internals & Diagnostics

How ForgeWP protects system boundaries, manages Vite virtual modules, and provides self-healing tools.

Modern developer tools strive for zero clutter: your source code directory should contain your code, and internal compiler plumbing should stay out of your way.

ForgeWP achieves this through its Zero-Clutter Architecture. In this guide, you will learn how the framework manages virtual modules, what happens inside the hidden .forgewp/ directory, and how to use built-in diagnostic and repair tools to keep your project healthy.

The Zero-Clutter Architecture

ForgeWP uses a Zero-Clutter Architecture: your source directory contains your code, and internal compiler plumbing stays completely out of your way.

ForgeWP powers this using a Vite Virtual Module System:

Flowchart
Rendering diagram...
  1. Supported Imports: Import the hooks and components that exist in the installed packages:
src/app/page.tsx
1import { useWpTitle, useWpQuery, WpQueryLoop } from "@forgewp/react"
2   import { useWpAuth, WpAuthProvider } from "@forgewp/auth"
  1. Virtual Runtime Module: The Vite plugin loads CMS mock data from cms/ into the browser during development. The runtime module is virtual; this does not mean every framework helper or generated file in a project is virtual.
  2. Legacy Import Compatibility: The plugin still resolves legacy WordPress module paths for compatibility. New code should import from the documented package entry points instead.

The Hidden .forgewp/ Directory

At the root of your project, you will notice a hidden .forgewp/ directory. This folder functions exactly like .next/ in Next.js or .astro/ in Astro:

Hidden Compiler Cache (.forgewp/)
my-theme/
└── .forgewp/
  ├── cache/               # Build caches, including image and font caches
  ├── out/
  │   └── my-theme/        # Generated WordPress theme directory
  └── my-theme.zip         # Final compiled theme archive
Treat `.forgewp/` as generated output

It contains build caches, the generated theme directory, and the exported ZIP. Do not edit generated theme files there; change the source and export again. Keep the directory out of version control unless your deployment workflow intentionally tracks exported artifacts.

Health Checks with forgewp doctor

Whenever you encounter unexpected behavior, install new npm packages, or prepare to export a production theme, you can run the built-in diagnostic doctor:

Terminal
pnpm forgewp doctor

The doctor runs project checks for the current environment. The report varies depending on missing files, warnings, and whether a production build exists:

Terminal — forgewp doctor
🩺   FORGEWP SYSTEM DOCTOR

  Checking Node.js Runtime Environment................... ✅ OK
  Checking User Configuration & HTML Layout.............. ✅ OK
  Checking Mock Database Schema Integration.............. ✅ OK
  Checking System Internal Framework Libraries........... ✅ OK
  Checking Tailwind Styling Architecture................. ✅ OK
  Checking Active Hydration Islands Diagnostics.......... ⚠️ WARNING

────────────────────────────────────────────────────────────
⚠️ SYSTEM READY WITH WARNINGS: review the recommendations before export.

What Each Check Validates:

  1. Node.js Runtime Environment: The doctor checks ^22.18.0 || >=24.11.0, matching the compiler dependencies. See System Requirements for the current toolchain.
  2. User Configuration & HTML Layout: Ensures wp.config.ts, package.json, and index.html exist and that wp.config.ts exports a valid configuration without syntax errors.
  3. Mock Database Integration: Checks that cms/mock-data.ts or cms/mock-data.json exists. JSON data is parsed; TypeScript mock data is not fully schema-validated by this check.
  4. System Internal Framework Libraries: Ensures all required framework configuration blueprints are present.
  5. Tailwind Styling Architecture: Confirms that your global Tailwind CSS stylesheet (src/app/globals.css or src/index.css) exists and is properly imported.
  6. Hydration Diagnostics: Scans source for interactive islands. If a Vite build manifest is available, it also reports resolved island chunks and bundle-size findings; it does not require or scan for a 'use client' directive.

Self-Healing with forgewp repair

If you accidentally delete a critical configuration blueprint, or if a team member checks out a branch with missing framework templates, you do not need to delete your repo and start over.

Run the self-healing repair tool:

Terminal
pnpm forgewp repair
Terminal — forgewp repair
🔧   FORGEWP SYSTEM REPAIR TOOL

  ✅ Restored/Healed: vite.config.ts
  ✅ Restored/Healed: tsconfig.json
  ✅ Restored/Healed: components.json
  ✅ Seeded Default Database: cms/mock-data.ts

────────────────────────────────────────────────────────────
🎉 REPAIR COMPLETE: Successfully repaired/synced 4 core framework elements.
   All protected boundaries have been restored back to defaults. Build safe!
Back up JSON mock data first

forgewp repair does not overwrite React components in src/app/ or src/blocks/, but it force-writes its JSON blueprints when a matching .ts file is not present. If you customized cms/mock-data.json, cms/menus.json, or another blueprint JSON file, back it up or migrate it to the supported typed .ts form before running repair.

Clearing Stale Caches with forgewp clean

If you change large amounts of code or switch branches, you can remove generated build output and caches with:

Terminal
pnpm forgewp clean

This removes .forgewp/, dist/, and .vite/ from the current project. That includes the generated theme directory and ZIP inside .forgewp/, not just caches. Keep a copy of any export you still need; the next build or export regenerates these artifacts from source.

Summary Checklist: What to Edit vs Leave Alone

Table · 3 columns
Directory / File
Edit Freely?
Notes
src/app/**
YES
Your pages, layouts, routes, and styles.
src/blocks/**
YES
Your custom Gutenberg blocks.
cms/**
YES
Your offline mock content, menus, and options.
wp.config.ts
YES
Theme identity, colors, typography, and bounds.
.forgewp/**
NO
Managed exclusively by compiler; do not touch.
dist/**
NO
Compiled Vite production output.

Next Up

Congratulations! You now have a comprehensive understanding of your theme's project anatomy, configuration, mock data layer, and system diagnostics.

In WordPress Basics, we will explore core WordPress concepts that every React developer should know — including Block Themes vs. Classic Themes, The WordPress Content Model, and The Template Hierarchy Demystified. Proceed to Block Themes vs. Classic Themes.