The fastest and most reliable way to start a new ForgeWP theme is using the official scaffolding tool: create-forgewp.

The CLI sets up a clean, pre-configured theme workspace with React 19, Tailwind CSS 4, TypeScript, and the ForgeWP compiler ready to go.

---

Step 1: Run the Scaffolding Command

Open your terminal, navigate to the folder where you keep your coding projects, and run:

pnpm dlx create-forgewp my-theme

Replace my-theme with whatever folder name you want to give your project (e.g. agency-theme or modern-blog).

---

Step 2: Interactive CLI Prompts

The CLI will launch an interactive wizard directly in your terminal. Here is a breakdown of each prompt and what it means:

⚡ FORGEWP — React & Tailwind CSS for WordPress
  Creating a lightweight, modern block-theme project scaffold.

✔ Theme Name … Velvet & Oak
✔ Framework adapter … React
✔ Choose aesthetic style preset … Shadcn (Smooth modern curves)
✔ Select optional features to include … WooCommerce E-Commerce
✔ Install NPM dependencies now? … Yes
✔ Choose your package manager … pnpm

1. Theme Name

Enter the human-readable display name for your WordPress theme (e.g., Velvet & Oak or Apex Portfolio).

• The CLI automatically converts this into a sanitized slug (velvet-oak) for your folder, package name, and WordPress textDomain.

2. Framework Adapter

Choose how you want to build your theme:

• React (Recommended): Uses React 19, TypeScript, and JSX components with selective hydration islands and native Gutenberg block support.
• HTML: Generates a clean, static HTML template scaffold for developers who prefer raw HTML/CSS authoring.

3. Aesthetic Style Preset

Choose your default design language:

• Shadcn (Default): Smooth modern curves, balanced padding, and Radix UI primitives.
• ForgeWP (Sharp geometric corners): High-contrast, editorial typography with sharp edges (Coming soon).

4. Optional Features (Multi-Select)

Press <Space> to toggle features, and <Enter> to confirm:

• WooCommerce E-Commerce: Adds starter product archives, cart drawers, and single product templates.
• Developer Auth Sandbox: Adds mock authentication and user login flows for membership themes.

5. Install Dependencies & Package Manager

Choose Yes to let the CLI automatically install dependencies using your chosen package manager (pnpm, npm, yarn, or bun).

---

Step 3: Non-Interactive & Automation Flags

If you are running automated scripts, testing in CI/CD, or prefer skipping interactive prompts, you can pass command-line flags:

# Accept all recommended defaults immediately
pnpm dlx create-forgewp my-theme --yes

# Skip dependency installation (useful for manual installs or slow connections)
pnpm dlx create-forgewp my-theme --no-install

# Specify project name explicitly via flag
npx create-forgewp --projectName="velvet-oak" --yes

---

Step 4: Tour of Your Scaffolded Project

Once the command finishes, navigate into your new project directory:

cd my-theme

Open the folder in your code editor. You will see a clean, organized project structure:

my-theme/
├── cms/                     # Local CMS simulation layer (mock posts, pages, menus)
│   ├── mock-data.ts         # Realistic posts, authors, and featured images
│   ├── menus.ts             # Sample header and footer navigation menus
│   ├── site-options.ts      # WordPress site settings (title, tagline)
│   └── theme-mods.ts        # Customizer & design tokens
├── src/
│   └── app/                 # Your theme's React components and layouts
│       ├── layout.tsx       # Global layout wrapper (Navbar, Footer, HTML shell)
│       ├── page.tsx         # Main homepage component
│       └── globals.css      # Tailwind CSS 4 design tokens and utilities
├── wp.config.ts             # WordPress theme configuration (colors, fonts, sizes)
├── vite.config.ts           # Vite dev server and ForgeWP compiler config
└── package.json             # Project dependencies and build scripts

---

Next Step: Launching the Dev Server

With your theme project created, let's start the development server and see your theme come to life in the browser!

Proceed to Run The Dev Server.