The ForgeWP export pipeline is the bridge between modern React component authoring and production WordPress hosting. During development, you write React, Tailwind CSS, TypeScript, and CMS schemas with instant Hot Module Replacement (HMR). When you are ready to deploy, the compiler transforms that entire project into a self-contained, standards-compliant WordPress theme package.

The generated theme requires zero Node.js runtime on your WordPress server. The production host only requires standard PHP and WordPress. All server rendering is pre-compiled into native PHP templates, and interactive React features are bundled into optimized selective hydration islands.

Run a Production Export

To compile your theme for production, run the export command from your project root:

Alternatively, invoke the ForgeWP CLI directly:

The command runs in non-destructive mode: it compiles assets, renders static templates, generates PHP and configuration files, runs asset optimization pipelines, and creates an installable ZIP archive inside the .forgewp/ directory. It does not alter your local database or modify any external servers.

Terminal Progress Walkthrough

When you trigger pnpm export, the interactive CLI displays each pipeline phase in real time:

Generated Theme Output Anatomy

Once the export finishes, your theme package is organized inside the .forgewp/ folder:

Uncompressed Folder versus ZIP Archive

• .forgewp/out/<theme-slug>/: The uncompressed WordPress theme directory. Use this folder for local inspection, automated CI/CD deployments, Git-based theme deployments, or direct rsync/SFTP syncing to wp-content/themes/.
• .forgewp/<theme-slug>.zip: A standard ZIP archive containing the uncompressed theme folder at its root. Upload this archive directly through the WordPress admin dashboard (Appearance → Themes → Add New → Upload Theme).

The Eight Export Stages Under the Hood

The ForgeWP compiler executes eight discrete stages during every export:

1. Preflight Safeguards and Self-Healing

Before building, validateCriticalFiles() inspects your workspace. It confirms that essential authoring files exist (wp.config.ts, package.json, index.html, src/main.tsx, src/app/layout.tsx, src/app/routes.tsx). If any required system files are missing or out of date, ForgeWP restores them from pre-compiled system blueprints automatically.

2. Selective Island Splitting

splitInteractiveIslands() analyzes your component source code. Components that mix static JSX markup with interactive handlers (onClick, useState, framer-motion) are automatically separated into a static server shell and an extracted hydration island located in .forgewp-islands/.

3. Block Wrapper Pre-Scaffolding

scanAndGenerateBlocks() scans components declared with defineBlock(). It generates entry wrappers in .forgewp-blocks/ so Vite and Rollup register them as compilation entry points for Gutenberg block editors.

4. Vite Asset Compilation

buildAssets() invokes Vite in production mode. It bundles all Tailwind CSS, React runtime libraries, and selective hydration chunks, outputting optimized bundles and a .vite/manifest.json file into dist/.

5. Static Markup Pre-Rendering

renderStaticMarkup() executes a Node SSR pass of your React application. It generates static HTML fragments for the header, footer, front page, 404 page, archive feeds, single post templates, and custom page templates.

6. Asset Optimization Pipeline

ForgeWP inspects all local images and web fonts:

• Sharp Image Pipeline: Scans images referenced in components and generates responsive WebP variants with configurable quality (wp.config.ts assets setting).
• Web Font Orchestration: Downloads Google Fonts or external fonts declared in your configuration, converts them to WOFF2, places them in assets/fonts/, and writes local @font-face rules.

7. WordPress Core and Block Theme Generation

generateTheme() writes all WordPress PHP files and configuration artifacts:

• functions.php: Registers nav menus, custom post types, taxonomies, REST form endpoints, Polylang strings, and script enqueues.
• theme.json: Translates color palettes, font sizes, layout widths, and spacing declared in wp.config.ts into standard WordPress Block Theme tokens.
• style.css: Injects the required WordPress theme header comment (Theme Name, Theme URI, Author, Version, Text Domain).
• PHP Templates: Wraps static HTML fragments with WordPress template tags (wp_head(), wp_footer(), have_posts(), the_post()).

8. Packaging and Performance Reporting

zipTheme() packages the uncompressed theme folder into a level-9 compressed ZIP archive. Finally, printAssetDiagnosticsReport() outputs a concise bundle summary table to the console.

Inspecting Key Generated Theme Files

Before deploying your theme to a live WordPress server, inspect these essential files to understand how your React code was translated:

1. style.css (WordPress Theme Declaration)

WordPress requires a style.css file in the theme root with specific header comments. ForgeWP generates this header from your wp.config.ts metadata:

2. theme.json (WordPress Block Theme Configuration)

ForgeWP translates your design system settings from wp.config.ts into a complete WordPress theme.json file:

This guarantees that WordPress block editors, site settings, and core blocks inherit your exact React theme palette and typography tokens.

3. functions.php (Theme Setup & Hydration Enqueues)

The generated functions.php orchestrates all theme features:

• Registers theme supports (post-thumbnails, title-tag, menus, align-wide).
• Registers custom post types and custom taxonomies with Polylang translation support.
• Enqueues compiled CSS (wp_enqueue_style) and the React runtime script (wp_enqueue_script).
• Injects the hydration manifest, menu trees, site options, and REST nonces into window.forgeWpHydration.
• Enqueues the forgewp-hydrator.js micro-hydrator orchestrator.
• Registers dynamic translation keys with Polylang via pll_register_string().

4. Template Wrappers (front-page.php, page.php, single.php)

Rather than rendering complex React markup on every PHP request, template files serve pre-compiled static HTML fragments while preserving native WordPress template tags:

Run Preflight Checks with Doctor and Typecheck

Before exporting a release package for a client or staging environment, run automated diagnostics:

1. TypeScript Verification

Confirms that all React components, configuration files, and CMS data schemas satisfy strict TypeScript type checks.

2. ForgeWP System Doctor

The system doctor runs seven comprehensive diagnostic checks:

If the doctor discovers issues (such as missing system files, invalid JSON in mock data, or hydration islands exceeding 100 kB), it outputs actionable guidance. You can run pnpm forgewp repair to automatically restore missing internal blueprints.

Export Validation Flags

ForgeWP provides CLI flags for validation and automation in continuous integration (CI) pipelines:

Running Validated Strict Exports in CI/CD

To guarantee zero missing assets or unresolved schema mappings in your release pipeline, combine --validate and --strict:

The validation suite verifies:

1. All required WordPress theme files (functions.php, style.css, index.php, header.php, footer.php, theme.json) exist and are non-empty.
2. All static HTML fragments in forgewp-static/ exist and contain content.
3. Every detected selective hydration island has a compiled JavaScript chunk in assets/.
4. functions.php correctly references all compiled CSS and JS asset paths.
5. style.css contains valid Theme Name: and Text Domain: headers.
6. theme.json contains valid JSON and schema versioning.
7. Any WooCommerce loops wrap dynamic price and rating outputs with wp_kses_post() for security.

If any check fails in strict mode, the command exits with code 1, preventing flawed builds from reaching production.

Clean Caches Between Builds

If you make significant architectural changes or encounter stale build artifacts, clear your temporary directories before building:

The cleaner removes .forgewp/, dist/, and .vite/ cache folders. Once cleaned, run pnpm export to produce a completely clean, fresh release.

Summary Checklist

Before uploading your exported theme to a WordPress host:

• Run pnpm typecheck to confirm zero TypeScript errors.
• Run pnpm forgewp doctor to confirm project health.
• Run pnpm forgewp export --validate --strict to build and validate the release package.
• Confirm that .forgewp/<theme-slug>.zip exists and is non-empty.
• Verify that your theme metadata (name, slug, version, textDomain) in wp.config.ts is up to date.

Next Steps

Now that you have exported and validated your production theme package, proceed to Install and Verify the Theme in WordPress to learn how to install your theme, verify WordPress database connections, test interactive islands, and execute safe zero-downtime releases.