Core Framework/guides/Project Anatomy

Project Directory Map

A complete guided tour of every file and folder in a scaffolded ForgeWP theme.

On This Page

When you scaffold a new theme with create-forgewp, the CLI creates a lightweight, modern project workspace. Unlike traditional WordPress themes which are packed with complex PHP template files, ForgeWP organizes your workspace like a standard modern React application.

Here is the complete layout of a freshly generated ForgeWP theme:

Project Directory Structure

my-theme/
├── cms/                         # Offline WordPress database & content simulation
│   ├── menus.ts                 # Navigation menus (header, footer, mobile)
│   ├── mock-data.ts             # Sample posts, authors, tags, and categories
│   ├── site-options.ts          # Blog name, tagline, date formats
│   ├── theme-mods.ts            # Customizer values and theme modifications
│   ├── translations.ts          # Localized language dictionaries
│   └── screenshot.png           # 1200x900 theme preview image for WP Admin
│
├── src/                         # Your React & styling source code (100% clean)
│   ├── app/                     # Page routes, layouts, and global styles
│   │   ├── globals.css          # Tailwind CSS 4 theme rules & custom CSS
│   │   ├── layout.tsx           # Global site shell (Header, Footer, Providers)
│   │   ├── layouts/             # Reusable page layout wrappers
│   │   │   ├── default.tsx      # Standard content layout with main wrapper
│   │   │   └── blank.tsx        # Minimal canvas for landing funnels
│   │   ├── page.tsx             # Theme homepage template (front-page)
│   │   ├── routes.tsx           # Dev server navigation switchboard
│   │   ├── query-sandbox.tsx    # Loop testing sandbox for query patterns
│   │   └── repeater-sandbox.tsx # Repeater and custom field preview canvas
│   ├── blocks/                  # Custom Gutenberg block components
│   │   └── WpEditableArticle.tsx # Example editable visual block
│   ├── lib/                     # Reusable helper utilities
│   │   └── utils.ts             # Tailwind className merger (cn helper)
│   ├── main.tsx                 # Dev server client entry mount
│   └── vite-env.d.ts            # Vite client TypeScript ambient declarations
│
├── .forgewp/                    # Hidden compiler cache & staging build area
├── dist/                        # Vite compiled client bundles & assets
├── components.json              # Shadcn UI configuration & component registry
├── index.html                   # Vite development preview HTML entry point
├── package.json                 # Project dependencies, scripts, and commands
├── tsconfig.json                # TypeScript compiler configuration
├── vite.config.ts               # Vite 6 + Tailwind 4 build configuration
└── wp.config.ts                 # Master ForgeWP theme settings & theme.json config

The Four Project Zones

To navigate your project with confidence, think of your workspace as four distinct functional zones:

Flowchart

Rendering diagram...

Zone 1: Application Source Code (`src/`)

This is where you will spend almost all of your development time. Everything in src/ is pure TypeScript, React 19, and Tailwind CSS 4.

Zero Clutter Guarantee

Notice that src/ does not contain any hidden framework plumbing, generated PHP files, or temporary bridges. You write standard React code and import directly from canonical packages like @forgewp/react.

src/app/page.tsx: Your homepage canvas. This component maps directly to the WordPress front-page template (front-page.html or index.html).
src/app/layout.tsx: The top-level wrapper that surrounds every page in your theme. Use this for your global navigation bar, site header, announcements banner, and footer.
src/app/layouts/default.tsx: The default layout wrapper component that provides structured <main> container bounds for standard WordPress template views.
src/app/layouts/blank.tsx: A minimal, distraction-free layout wrapper ideal for splash pages, custom authentication views, and full-bleed landing pages.
src/app/globals.css: The stylesheet where you import Tailwind CSS 4 (@import "tailwindcss";) and declare your custom design utilities and theme layer variables.
src/app/routes.tsx: A client-side router that lets you switch between templates (single post, archive, 404, query sandbox) while developing offline.
src/blocks/: Dedicated folder for custom Gutenberg blocks. A component becomes a block when it exports a defineBlock() definition from this area, or when it is annotated with @forgewp-block and discovered by the compiler. The annotation path can live in another src/ folder and generates a wrapper under src/blocks/generated/.
src/lib/utils.ts: Standard utility functions, including the popular cn() helper (combining clsx and tailwind-merge) for flexible conditional styling.

Zone 2: CMS Simulation Layer (`cms/`)

In traditional WordPress development, you cannot preview a template without running a local web server (like Apache or Nginx), a MySQL database server, and a full WordPress PHP installation.

ForgeWP completely removes that requirement. The cms/ folder acts as your local offline database:

Table · 3 columns


File	Purpose	WordPress Equivalent
`mock-data.ts`	Posts, pages, authors, dates, tags, and featured images	`wp_posts` & `wp_postmeta`
`menus.ts`	Navigation links, nested dropdowns, and target URLs	`wp_nav_menu`
`site-options.ts`	Site name, tagline, admin email, language, date format	`wp_options` (`get_option()`)
`theme-mods.ts`	Customizer settings and theme options	`get_theme_mod()`
`translations.ts`	Localized string tables for multilingual themes	`.mo` and `.po` language files
`screenshot.png`	1200×900 image displayed in WordPress Themes list	Theme screenshot card

Vite watches supported files in cms/ and refreshes the preview when they change. Do not use pnpm fresh to restore mock data: it is a destructive factory reset that can remove scaffolded source files. Keep mock data in version control so you can restore an earlier version safely.

Where are `functions.php` and `style.css`?

If you come from classic WordPress, you might expect to see functions.php and style.css in your root project folder. In ForgeWP, you never write these manually! The compiler automatically generates pristine functions.php and style.css files inside .forgewp/out/<theme-name>/ during export, registering your menus, enqueuing assets, and declaring metadata on your behalf.

Zone 3: Configuration Files (Root)

These root files define your theme's metadata, design system tokens, and compiler behavior:

wp.config.ts: The master brain of your theme. Defines theme name, slug, text domain, layout container bounds (contentSize, wideSize), color palette, and Google Fonts. The compiler converts this file 1:1 into WordPress's native theme.json v3.
vite.config.ts: Configures Vite 6, Tailwind CSS 4 (@tailwindcss/vite), React Fast Refresh (@vitejs/plugin-react), and the @forgewp/compiler virtual module plugin.
components.json: Standard configuration file for Shadcn UI. This allows you to install accessible Radix UI primitives directly into your theme.
package.json: Declares your npm scripts (pnpm dev, pnpm build, pnpm export, pnpm fresh, pnpm forgewp) and dependencies.
index.html: The HTML shell used exclusively by Vite during local development. It is never included in the final exported WordPress theme.

Zone 4: Build & Cache Artifacts (`.forgewp/` & `dist/`)

.forgewp/: A hidden directory generated by the compiler (identical in purpose to .next/ in Next.js or .astro/ in Astro). It stores intermediate PHP templates, hydration island manifests, compiler cache files, and the final .zip theme archive.
dist/: The output folder where Vite compiles optimized CSS and client-side JavaScript bundles for selective hydration islands.

Never Hand-Edit Generated Artifacts

Files inside .forgewp/ and dist/ are automatically generated and completely overwritten every time you build or export. Always author your changes in src/ and wp.config.ts.

The 80/20 Rule: What You Actually Edit

As a theme author, you do not need to manage every file in the directory tree on a daily basis. Here is how your development time is typically distributed: