ForgeWP

The cms/ Simulation Layer

How ForgeWP emulates WordPress posts, menus, site options, and translations offline with zero Docker or MySQL setup.

One of the biggest friction points in traditional WordPress theme development has always been local environment setup. Before you could write a single line of CSS, you had to install Docker, LocalWP, or a local LAMP stack (Apache, MySQL, PHP), import database dumps, and configure local virtual hosts.

ForgeWP completely eliminates this requirement with the cms/ Simulation Layer.

The Zero-Backend Philosophy

During local development, ForgeWP acts as its own offline WordPress emulator. The cms/ folder in your project root contains typed data structures that simulate a live WordPress database:

Flowchart
Rendering diagram...
  • In Development (pnpm dev): Your React components receive data directly from cms/. You can design your theme, test complex grid layouts, and preview typography with instant hot reload.
  • In Production (pnpm export): The compiler removes the mock data layer entirely. Instead, it replaces your mock bindings with native WordPress PHP template tags (the_title(), have_posts(), wp_nav_menu()). When installed on a live WordPress site, your theme reads real data from the WordPress MySQL database.
Will my mock data in `cms/` end up in the exported production theme?

Never. The cms/ folder is exclusively used by Vite during local development. When you run pnpm export, the compiler substitutes mock data bindings with native WordPress PHP query functions (have_posts(), the_post(), get_post_meta()). The output theme ZIP contains zero mock data and zero references to your cms/ directory.

Anatomy of the cms/ Directory

Here is a breakdown of each file inside cms/ and how it is structured using official ForgeWP helpers:

1. cms/mock-data.ts (Posts & Pages)

Contains your sample posts, pages, categories, and tags. You define mock data using the defineWpPosts helper from @forgewp/react:

cms/mock-data.ts
1import { defineWpPosts } from "@forgewp/react"
2
3export const mockData = defineWpPosts({
4  post: [
5    {
6      id: 1,
7      title: "Designing with ForgeWP and React 19",
8      slug: "designing-with-forgewp-react-19",
9      excerpt:
10        "Learn how modern component architecture is transforming WordPress themes.",
11      content: "<p>WordPress themes no longer need messy PHP templates...</p>",
12      date: "May 12, 2026",
13      author: "Elena Rostova",
14      featuredImage:
15        "https://images.unsplash.com/photo-1498050108023-c5249f4df085",
16      categories: ["Design", "Development"],
17      tags: ["React", "Tailwind", "Gutenberg"],
18      customFields: {
19        readTime: "4 min",
20        featuredStatus: true,
21      },
22    },
23  ],
24  page: [
25    {
26      id: 10,
27      title: "About Our Studio",
28      slug: "about",
29      content: "<p>We build high-performance digital experiences.</p>",
30    },
31  ],
32})
33
34export default mockData

2. cms/menus.ts (Navigation Menus)

Defines header navigation items, sub-menus, mobile drawers, and footer links using defineWpMenus:

cms/menus.ts
1import { defineWpMenus } from "@forgewp/react"
2
3export const menus = defineWpMenus({
4  primary: [
5    { title: "Home", url: "/" },
6    { title: "About", url: "/about" },
7    { title: "Blog", url: "/blog" },
8    { title: "Contact", url: "/contact" },
9  ],
10  footer: [
11    { title: "Privacy Policy", url: "/privacy" },
12    { title: "Terms of Service", url: "/terms" },
13  ],
14})
15
16export default menus

3. cms/site-options.ts (Site Settings & Options)

Simulates values stored in the WordPress wp_options table using schema helpers from @forgewp/react/config:

cms/site-options.ts
1import {
2  defineWpOptions,
3  optionText,
4  optionUrl,
5  optionEmail,
6} from "@forgewp/react/config"
7
8export const siteOptions = defineWpOptions({
9  contact_phone: optionText({
10    label: "Contact Phone",
11    default: "+1 (555) 019-9000",
12  }),
13  contact_email: optionEmail({
14    label: "Contact Email",
15    default: "admin@forgewp.local",
16  }),
17  social_facebook: optionUrl({
18    label: "Facebook URL",
19    default: "https://facebook.com",
20  }),
21  social_instagram: optionUrl({
22    label: "Instagram URL",
23    default: "https://instagram.com",
24  }),
25})

4. cms/theme-mods.ts (Theme Customizer Settings)

Simulates values set via the WordPress Theme Customizer or theme modifications (get_theme_mod()):

cms/theme-mods.ts
1export const themeMods = {
2  custom_logo: "",
3  header_textcolor: "#0f172a",
4  footer_text: "© 2026 ForgeWP. All rights reserved.",
5}

5. cms/translations.ts (Multilingual Dictionaries)

Defines localized string dictionaries for multilingual themes using defineTranslations:

cms/translations.ts
1import { defineTranslations } from "@forgewp/react"
2
3export const translations = defineTranslations({
4  en: {
5    welcome: "Welcome to ForgeWP",
6    readMore: "Read More",
7    searchPlaceholder: "Search articles...",
8  },
9  de: {
10    welcome: "Willkommen bei ForgeWP",
11    readMore: "Weiterlesen",
12    searchPlaceholder: "Artikel durchsuchen...",
13  },
14})
15
16export default translations

6. cms/screenshot.png

A 1200×900 image that serves as the official theme preview screenshot. When your theme is exported and installed in WordPress, this image is displayed on the Appearance → Themes screen.

Instant Hot Reloading with Vite

ForgeWP automatically watches every file in cms/. Whenever you modify a post title, add a new tag, or edit a menu link, the Vite dev server triggers an immediate Fast Refresh in your browser:

Vite Console Output
[vite] page reload cms/mock-data.ts

This gives you a tight, lightning-fast feedback loop: you can test how your design handles long post titles, missing featured images, or deeply nested navigation menus without touching a database or restarting any servers.

Restoring Mock Data

Treat cms/ mock files like source code and keep them in version control. Restore a previous version with your normal Git workflow or edit the file directly. pnpm fresh is not a mock-only reset: it can delete scaffolded pages, blocks, and components. pnpm forgewp seed:mock-data configures WordPress-side data seeding for theme activation; it does not restore local mock files.

Use Client Content During Design

Before finalizing your theme, paste realistic sample content from your client into cms/mock-data.ts. Designing with realistic headlines, varied paragraph lengths, and real photography reveals layout flaws early — before you ever deploy to WordPress.

Next Steps

Now that you know how the CMS simulation layer powers your offline preview, proceed to Framework Internals & Diagnostics — how ForgeWP protects system boundaries and how tools like forgewp doctor keep your project healthy.