ForgeWP

create-forgewp Scaffolder Reference

Complete technical reference for the create-forgewp project scaffolding CLI: interactive wizard options, automation flags, framework adapters, and CI/CD project initialization.

create-forgewp is the official scaffolding CLI for initiating new ForgeWP theme projects. It sets up a fully configured theme workspace with React 19, TypeScript, Tailwind CSS 4, Vite, and offline CMS simulation in seconds.

You run it using your package manager without globally installing any packages:

Terminal
# With pnpm (recommended)
pnpm create forgewp [project-directory] [options]

# With npm
npm create forgewp@latest [project-directory] [options]

# With bun
bun create forgewp [project-directory] [options]

# With yarn
yarn create forgewp [project-directory] [options]
Flowchart
Rendering diagram...

1. Interactive Project Creation

Running pnpm create forgewp with no arguments launches an interactive prompt wizard that guides you through project setup:

Prompt 1: Project Directory / Theme Name

Interactive Prompt
? Project name: alpine-resort
? Theme Name: Alpine Resort
  • Project Directory: The directory name where files are written. Automatically validated to ensure valid characters and that the destination folder does not conflict with existing files.
  • Theme Name: The human-readable title shown in the WordPress Appearance → Themes dashboard. Automatically defaulted to Title Case based on your folder slug.

Prompt 2: Framework Adapter

Interactive Prompt
? Framework adapter:
  > React (Recommended: React 19, TypeScript, Tailwind CSS 4)
    HTML (Static HTML starter with template parts)
  • React: Full-featured React 19 component authoring with Gutenberg block compilation, selective hydration islands, and offline CMS simulation.
  • HTML: Lightweight static HTML starter for developers who prefer authoring pure HTML fragments without React.

Prompt 3: Aesthetic Style Preset

Interactive Prompt
? Choose aesthetic style preset:
  > shadcn (Modern rounded layout with flexible UI primitives)
    forgewp (Sharp, technical aesthetic with geometric zero-radius borders)
  • shadcn: Default design token configuration with comfortable radius tokens (rounded-xl, rounded-md) matching modern application standards.
  • forgewp: Distinctive brutalist/technical aesthetic featuring sharp geometric borders (rounded-none).

2. Non-Interactive CLI Flags

For continuous integration (CI) workflows, Docker environments, or quick automated scaffolding, create-forgewp provides complete non-interactive command-line flags:

Terminal
npx create-forgewp [project-directory] [options]

Options Reference

Table · 4 columns
Flag
Type
Default
Description
-y, --yes
boolean
false
Bypasses all interactive prompts and applies default settings.
--projectName <name>
string
undefined
Specifies the project folder name explicitly.
--adapter <name>
"react" | "html"
"react"
Selects the framework adapter engine.
--style <name>
"shadcn" | "forgewp"
"shadcn"
Selects the design token aesthetic preset.
--no-install
boolean
false
Skips running the package manager installation step (pnpm install).
-h, --help
boolean
false
Prints available command options and examples.

3. Automation & CI/CD Examples

Instant Scaffolding with Defaults

Create a project immediately without any interactive questions:

Terminal
pnpm create forgewp my-new-theme --yes

This creates my-new-theme/ using the React adapter, shadcn style preset, and automatically runs pnpm install.

Fast Scaffolding Without Dependency Installation

Scaffold the directory structure and config files without downloading node_modules (ideal for Docker images or custom caching layers):

Terminal
pnpm create forgewp custom-portal --adapter=react --style=shadcn --no-install

Explicit Project Name Parameter

Terminal
npx create-forgewp --projectName my-agency-theme --yes

4. Package Manager & Workspace Intelligence

create-forgewp automatically detects your working environment to ensure seamless integration:

1. Package Manager Detection

The CLI inspects how it was invoked (npm_config_user_agent) and locks into your active package manager:

  • If invoked via pnpm create forgewp, dependencies are installed via pnpm install.
  • If invoked via bun create forgewp, dependencies are installed via bun install.
  • If invoked via yarn create forgewp, dependencies are installed via yarn install.
  • If invoked via npm create forgewp, dependencies are installed via npm install.

2. Monorepo & Workspace Integration

If you run create-forgewp inside an existing pnpm-workspace.yaml monorepository, the scaffolder automatically detects the workspace root. It registers the new theme package into the workspace and configures internal package links (@forgewp/react, @forgewp/compiler) without polluting global dependencies.

5. Scaffolded Project Anatomy

Running create-forgewp produces a clean, pre-configured project tree ready for immediate development:

Scaffolded Theme Directory Structure
my-theme/
├── src/
│   ├── app/
│   │   ├── layout.tsx         # Global theme layout shell
│   │   ├── page.tsx           # Front page template (front-page.php)
│   │   ├── single.tsx         # Single blog post template (single.php)
│   │   ├── archive.tsx        # Post archive template (archive.php)
│   │   ├── 404.tsx            # Not found template (404.php)
│   │   └── routes.tsx         # Route mappings and page registrations
│   ├── components/            # Reusable UI components
│   └── blocks/                # Custom Gutenberg editor blocks
├── cms/
│   ├── mock-data.ts           # Offline simulated posts, pages, and CPTs
│   ├── menus.ts               # Navigation menu definitions
│   ├── site-options.ts        # Theme options schema (Appearance -> Theme Options)
│   └── translations.ts        # Localized strings dictionary
├── public/                    # Static assets (favicon, images)
├── wp.config.ts               # Master theme configuration and design tokens
├── package.json               # Scripts (dev, export, doctor, repair)
├── tsconfig.json              # TypeScript compiler configuration
└── vite.config.ts             # Vite build pipeline with ForgeWP plugin

6. Next Steps After Scaffolding

Once scaffolding completes, navigate into the project and start the development server:

Terminal
cd my-theme
pnpm dev

Visit http://localhost:5173 to see your React theme running live with simulated WordPress content and instant Hot Module Replacement.

When you are ready to produce a deployable WordPress theme ZIP archive:

Terminal
pnpm forgewp export

Next Steps

Now that you understand the project scaffolding workflow, proceed to Common Errors & Troubleshooting to review error diagnosis, missing blueprint repairs, and debugging steps for local themes.