The wp.config.ts file is the master configuration file for a ForgeWP theme. It exports a type-safe configuration object wrapped in defineConfig() that controls theme identity, WordPress theme.json v3 design tokens, custom post types, taxonomies, forms, authentication, localization, and compiler build plugins.

During development, Vite and the CMS emulator use this file to configure styles, routes, and mock data. During production export (pnpm export), the compiler translates this configuration directly into WordPress style.css headers, theme.json presets, functions.php registrations, and REST API controllers.

1. Top-Level Schema Overview

WordPress block-style support and theme screenshots

presets.wordpressCoreStyles defaults to true. Setting it to false omits add_theme_support('wp-block-styles') from generated PHP. This controls WordPress's block-style theme support; it does not disable all WordPress styles or plugin styles. Check your exported blocks after changing it.

For the theme preview image shown in Appearance → Themes, add cms/screenshot.png to your project. Export copies that file to the theme root; when it is absent, the compiler uses its packaged fallback when available. A screenshot configuration property does not select the image.

Theme compatibility requirements

ForgeWP writes the following defaults to the exported style.css: WordPress 6.6 (the minimum for generated theme.json version 3) and PHP 7.4 (the existing generator baseline). These metadata values are not a test record for a particular site. Choose hosting versions supported by WordPress and your project's dependencies, then verify the exported theme there.

Use compatibility to raise either requirement. Add testedUpTo after testing your theme on that WordPress version; ForgeWP omits this header when you have not supplied it.

All three values must be numeric version strings such as "6.6" or "8.2.1". Requirements cannot be lower than the generator defaults, and testedUpTo cannot precede requiresWordPress. Unknown compatibility keys are rejected. This setting writes metadata; it does not change the exported code or run compatibility tests. Theme-directory submissions also need the headers required by the directory's review rules.

See the WordPress theme.json v3 reference and stylesheet header reference.

Below is the master shape of wp.config.ts. You do not need to declare every section; only name, slug, version, textDomain, and description are required for a minimal theme.

2. Theme Identity & System Properties

These properties define the theme metadata written into the generated style.css header and WordPress theme directory.

3. Design System & theme.json v3 (settings)

The settings block maps directly to the modern WordPress theme.json v3 specification and configures CSS custom property generation for Tailwind CSS 4.

Layout Constraints (settings.layout)

Controls default reading container widths and Gutenberg wide alignment bounds:

• contentSize (string, e.g. '760px'): Maximum width for centered post reading content.
• wideSize (string, e.g. '1280px'): Maximum width for Gutenberg alignwide blocks.

Color Palettes (settings.color)

Declares brand color presets. The compiler automatically exports these into theme.json (--wp--preset--color--<slug>) and creates bidirectional bindings for Tailwind utility classes (bg-brand, text-brand-dark):

Typography & Google Fonts (settings.typography)

Defines font scales, families, and automated font downloading:

• fontSizes (Array<{ name, slug, size }>): Type scale presets. Supports fluid responsive typography scales with CSS clamp().
• fontFamilies (Array<{ name, slug, fontFamily }>): Font stack declarations.
• googleFonts (string[]): Google Font family strings (e.g. ["Inter:400,600", "Space Grotesk:700"]). The font pipeline can download local .woff2 files into assets/fonts/ during export. Inspect the exported files and remote fallback behavior to configure font loading for your site.

4. Custom Post Types (postTypes)

Declares custom post types that ForgeWP automatically registers in WordPress via register_post_type() in functions.php:

Configuration Options

5. Custom Taxonomies (taxonomies)

Registers custom taxonomies in WordPress via register_taxonomy():

6. Internationalization (i18n)

Configures multi-language translation and automated machine translation pipelines:

Properties Reference

• locales (string[]): Array of ISO 639-1 language codes supported by the theme.
• defaultLocale (string): Primary fallback language code.
• provider (string): Translation engine used by pnpm forgewp i18n:translate. Supports 'local', 'deepl', 'google', and 'libretranslate'.
• cache (string): Optional project-relative JSON response-cache path used by i18n:translate. Omit to use only catalog-based skipping. See the cache workflow in the localization guide.
• providerConfig (object): Credentials and endpoint settings for remote translation services.

7. Native Forms Engine (forms)

Declares server-side form endpoints, validation contracts, notification templates, and spam defenses:

Form Fields Configuration

8. Authentication & User Management (auth)

Configures frontend authentication, session validation, and registration settings:

9. Database Seeding Strategies (seed)

Controls generated routines that copy development content from cms/ into WordPress. The mock-content and product seeders can run on activation and admin initialization, subject to their guards. Seeding is a database write, not just a preview feature.

Seed Strategies

• false: Disables the selected seeder (mockData or products), not every database write performed by the theme or plugins.
• "once": Uses a stored seed marker to skip later runs. The mock-content seeder also skips matching existing posts unless explicitly forced.
• "upsert": Re-runs when seed data changes. Matching posts can have content and supplied custom fields overwritten; client changes are not merged or automatically preserved.
• "force": Re-runs without the once/hash skip when invoked and guards permit it. Because the routines also run during admin initialization, this is not limited to theme activation.
• sideloadImages (boolean, default: true): Downloads remote CDN image URLs into the WordPress Media Library and attaches them as native featured image attachments.
• developmentOnly (boolean, default: true): Checks WP_DEBUG and skips automatic seeding when it is absent or false. This is not production-host detection. The generated WP-CLI seed command's --force bypasses this guard and seed/hash checks.

For a deployment that should not seed posts or products, set both mockData: false and products: false before export. Test updates against existing content; see Install and Verify.

10. CMS Blueprint Seeding API

In addition to wp.config.ts, ForgeWP theme projects use typed helper functions in cms/*.ts to author offline simulation data. All helpers are imported from @forgewp/react/config:

defineWpPosts() (cms/mock-data.ts)

Authoring type-safe posts, pages, and custom post types:

defineWpMenus() (cms/menus.ts)

Menu locations are named slots in a theme; menu entries are the links assigned to those slots. defineWpMenus() supplies starter entries. The compiler also registers locations discovered in that data.

To declare a location before adding links, use top-level menus in wp.config.ts. Set the displayed admin description through settings.menus:

The current exporter uses the keys of top-level menus; its string values do not set the displayed label. settings.menus sets that label explicitly and takes precedence over an inferred description such as Primary Navigation. Merge these fields into your existing settings object rather than adding a second one.

Declaring navigation menu structures:

defineWpOptions() (cms/site-options.ts)

Declaring site-wide options and auto-generating the Appearance → Theme Options admin dashboard:

Additional Blueprint Helpers

• defineWpThemeMods(mods): Declares WordPress Customizer theme modifications in cms/theme-mods.ts.
• defineTranslations(dict): Declares multilingual dictionaries in cms/translations.ts.
• defineWpUsers(users): Declares mock user profiles for authentication testing in cms/users.ts.
• defineWpRoles(roles): Declares role capability matrices in cms/roles.ts.
• definePageConfig(config): Import from @forgewp/react/config for autocomplete and type checking of page metadata. Export its returned object as pageConfig in the page module. It returns the object unchanged; a plain export const pageConfig = { ... } also works without an import. Options include layout, header, footer, and the standalone-discovery flag exportTemplate.

Next Steps

Now that you understand the complete configuration schema for wp.config.ts and the CMS blueprint data layer, proceed to the Command Reference to explore all available create-forgewp and forgewp developer commands, build flags, and diagnostic tools.

11. Site options and option builders

Register custom option schemas with options: siteOptions in wp.config.ts; import siteOptions from your cms/site-options.ts. themeMods: themeMods supplies theme-modification defaults. The file's presence and a hook reading a key do not by themselves establish every admin control; follow Site Options & Custom Fields for registration.

All option builders accept an options object with label? and a string default?:

Read a toggle as useWpOption("show_notice", "0") === "1" in an interactive component. For static PHP output, use a compiler-supported conditional pattern and inspect the generated template: a compile-time placeholder is a nonempty string, so comparing a placeholder in ordinary server-rendered JavaScript does not test the live WordPress value.

12. Form discovery, delivery, and permissions

Prefer one defineWpForm() call in cms/forms/<name>.ts for each form. The filename supplies the key used by useWpForm() or submitWpForm(). The compiler also accepts forms in wp.config.ts. If both declare the same key, the inline wp.config.ts contract wins and the loader prints a warning; keep one declaration per form.

The top-level formsAdminCapability defaults to manage_options. Changing it grants access to form management and stored submitted data, so choose the site's intended administrator capability deliberately.

See Native Forms for a complete implementation, storage/privacy behavior, transport configuration, and verification. A successful local simulation does not send real mail.

13. Compiler integration settings

frameworkAdapter selects the compiler's rendering adapter; stub is a testing/development adapter. Use react or html for the corresponding theme workflow. configVersion currently accepts 1; add it explicitly to avoid the missing-version warning.

Use a scalar strategy for all mock content, or a per-post-type map to select types independently. Strategies are false, true, once, upsert, and force; true selects the one-time strategy. In a map, omitted keys and false are disabled, including with the WordPress command?s --force flag. Enabled types keep independent seed hashes, so changes to one type do not reapply an unchanged upsert type. Use the earlier seed guidance before changing content on an existing site.

For metadata declarations, the optional SEO plugin, custom PHP, and the exported compiler APIs, continue to Metadata & Compiler Extensions.

Registration behavior in this version

Use the generated registration as the final contract when configuring a custom content type:

• postTypes keys are registered even without sample entries. Mock-data keys can also establish a CPT. Names must fit WordPress's 20-character limit.
• The generator applies labels, icon, hasArchive, rewrite, public, showInRest, and supports. Visibility and REST default to true. Omitting supports retains title, editor, thumbnail, custom fields, and excerpt; providing an array replaces that list, including an empty array. Keep showInRest: true and the editor feature when the type needs Gutenberg editing.

rewrite accepts false or an object with optional slug and withFront. A supplied slug must be a nonempty path without a URL origin, query, fragment, backslash, or newline; withFront must be boolean. Export reports potential exact matches between archive bases and configured Page paths. See CPT route diagnostics for the checks and site-level verification boundaries.

• Custom taxonomy associations are inferred from a CPT mock item's _terms keys. taxonomies customizes the inferred taxonomy's labels and hierarchy; adding a configuration key alone does not establish its association. The generated hierarchy defaults to true when omitted. Taxonomy public, showUi, and showInRest each default to true and honor explicit false values independently.

For example, an item under property in cms/mock-data.ts can contain _terms: { property_feature: [{ name: "Courtyard", slug: "courtyard" }] }. Use the same property_feature key in taxonomies. Local associations guide registration; saving live terms and assigning them to real posts is a separate WordPress content step.

These behaviors are worth checking when adapting a monorepo theme with a different content model. The registration code skips an already registered post type or taxonomy; an installed plugin may therefore own its final behavior.

Per-post-type mock seeding

For example, seed starter posts once, refresh project fixtures when their source changes, and leave Pages untouched:

A map is an explicit allowlist: any unlisted type is excluded. once also skips a type that already has published content. upsert can overwrite matching posts when that type's source changes; it does not merge client edits. force runs on each eligible invocation, while the command's --force also bypasses the development/marker guards for enabled types. Neither form of force enables a disabled or omitted type.

Scalar strategies retain their existing global marker. Map strategies use independent per-type markers; switching configuration forms is a deliberate change to seed behavior. Review it on a test site with existing content before deployment. Automatic theme activation keeps the same WP_DEBUG guard as admin initialization.

Configure content-type visibility and editing

For example, a project type can expose its title and editor without the default excerpt or thumbnail features:

The region association still comes from the project's mock _terms.region entries. These settings customize a registration owned by ForgeWP; an existing plugin registration is left unchanged. Boolean options must use actual true or false values, and supports must be an array of strings; invalid values fail configuration loading.

After export, inspect the registration and test the editor and REST behavior on WordPress. Changing these options changes registration behavior, not the stored posts or term assignments.

An explicit supports: [] is emitted as PHP false so WordPress leaves the feature set empty. Passing an empty PHP array would restore WordPress defaults; see WordPress feature-support handling.