ForgeWP

Run The Dev Server

How local development preview works, how ForgeWP simulates WordPress offline, and what to do when issues arise.

The local development server gives you an instant, interactive preview of your WordPress theme inside your browser while you author components.

Starting the Dev Server

From inside your theme directory (my-theme/), run:

Terminal
pnpm dev

(Or npm run dev, yarn dev, or bun dev depending on your package manager).

Within a split second, Vite will start the development server and print a local URL in your terminal:

Vite Dev Server Output
VITE v6.4.2  ready in 218 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Open http://localhost:5173 in your browser. You will see your newly scaffolded theme's homepage rendering live!

How ForgeWP Simulates WordPress Offline

When you run pnpm dev, your theme is not connected to a live WordPress server or MySQL database. Instead, ForgeWP uses an intelligent local CMS simulation layer inside the cms/ directory to provide realistic WordPress data:

Flowchart
Rendering diagram...

What Lives in cms/?

  • cms/mock-data.ts: Acts like a lightweight local WordPress database. It contains realistic sample blog posts, authors, featured images, categories, and tags.
  • cms/menus.ts: Simulates WordPress navigation menus (such as your Primary Header Menu and Footer Menu).
  • cms/site-options.ts: Provides site-level WordPress settings like site title (blogname), tagline (blogdescription), and admin email.
  • cms/theme-mods.ts: Simulates WordPress customizer theme modifications and design tokens.

Because of this simulation layer, you can design and test dynamic queries, blog post listings, and navigation menus entirely on your laptop—even on an airplane without an internet connection! Learn more in The cms/ Simulation Layer.

Instant Hot Module Replacement (HMR)

One of the greatest benefits of ForgeWP over traditional WordPress development is instant feedback:

  1. Open src/app/page.tsx in your code editor.
  2. Find the main heading text (e.g., Welcome to ForgeWP).
  3. Change it to Hello from My Custom WordPress Theme!.
  4. Press Save (Ctrl+S or Cmd+S).

Look at your browser: the heading updates in milliseconds without a full page refresh. Your state is preserved, and you never have to sit through slow browser reloads.

Why doesn't my browser do a full page refresh when I save files?

ForgeWP uses Vite's Hot Module Replacement (HMR). When you change a component or tweak CSS in src/app/, Vite swaps the modified code in memory within milliseconds without reloading the browser page or losing your current scroll position and component state.

Helpful Development Commands

Your package.json includes several helpful utility commands:

Table · 2 columns
Command
Purpose
pnpm dev
Starts the Vite local development server with instant HMR.
pnpm fresh
Destructive factory reset; removes scaffolded pages, blocks, and components.
pnpm typecheck
Runs the TypeScript compiler (tsc --noEmit) to verify that all props and types are valid.
pnpm build
Builds frontend production assets through Vite.
pnpm export
Runs the full ForgeWP compiler to produce an installable WordPress .zip theme.
Do not use `pnpm fresh` as a routine mock-data reset.

It deletes generated build output and can permanently remove files under src/app/pages/, src/blocks/, and src/components/. It also restores JSON mock-data blueprints when no corresponding typed .ts file exists. The command asks for confirmation when it detects scaffolded work; --force skips that protection. Back up or commit your project before using it.

Common Development Issues & Troubleshooting

1. Port 5173 Already in Use

If another application is using port 5173, Vite will automatically try the next available port (e.g. http://localhost:5174).

  • To specify a custom port manually, update the server block in vite.config.ts:
vite.config.ts
1server: {
2  port: 3000,
3}

2. "Command Not Found: forgewp" or Missing Packages

If you cloned a repository or skipped dependency installation during scaffolding, your project may be missing its node_modules directory.

  • Run pnpm install in your project root to install all dependencies.

3. Changes to cms/mock-data.json Not Appearing

The ForgeWP dev server automatically watches changes to files in the cms/ folder. If you edit cms/mock-data.json and do not see the update, simply refresh your browser tab, or stop the terminal (Ctrl+C) and re-run pnpm dev.

Ready to Build for WordPress?

Now that you have your development loop up and running, proceed to Export A WordPress Theme to learn how to turn this React project into an actual, installable WordPress theme ZIP!