ForgeWP

Export A WordPress Theme

How to compile your React and Tailwind project into an installable, production-ready WordPress theme ZIP.

Exporting builds your Vite assets, renders your React app to HTML, generates the WordPress PHP integration and theme files, compiles registered Gutenberg blocks, and packages the result as a standard theme .zip archive.

Step 1: Run the Export Command

From the root of your project directory, run:

Terminal
pnpm export

(Alternatively, you can run pnpm forgewp export or npx forgewp export).

The compiler will execute its 5-stage build pipeline, displaying real-time progress in your terminal:

Terminal — Compiler Output
⚡ FORGEWP EXPORT — velvet-oak v0.1.0

  [assets]     Building production client assets with Vite…
  [render]     Rendering React app to static HTML…
  [generate]   Generating WordPress theme templates (PHP & theme.json)…
  [images]     Optimizing static assets with Sharp…
  [package]    Creating installable theme archive…

  ✔ Export Complete!
  Directory:   .forgewp/out/velvet-oak/
  Theme ZIP:   .forgewp/velvet-oak.zip (1.2 MB)

What Happens Under the Hood

To understand what ForgeWP does during export, look at how it transforms your modern code into native WordPress structures:

Flowchart
Rendering diagram...
  1. Asset Build: Vite builds the CSS and any client-side entries needed by discovered or explicitly configured interactive islands and editor blocks.
  2. Static Rendering: The compiler renders the React app in Node.js to capture its initial HTML.
  3. WordPress Generation: The compiler processes recognized ForgeWP markers and generates PHP templates, functions.php, theme.json, and registered Gutenberg block files. Ordinary React components provide rendered markup; they are not all translated into PHP.
  4. Asset Processing: Sharp generates responsive WebP variants for eligible raster assets. The export also prepares fonts and preload metadata when configured and available.
  5. Packaging: The generated theme directory is written to .forgewp/out/<theme-slug>/; by default, ForgeWP also creates .forgewp/<theme-slug>.zip.

Inspecting the Output Directory

Open the .forgewp folder created in your project:

Compiled Theme Structure (.forgewp/)
my-theme/
└── .forgewp/
    ├── out/
    │   └── velvet-oak/              # The unzipped WordPress theme directory
    │       ├── assets/              # Built styles, scripts, fonts, and image variants
    │       ├── blocks/              # Compiled custom Gutenberg blocks
    │       ├── forgewp-static/      # Rendered HTML fragments used by PHP templates
    │       ├── 404.php
    │       ├── archive.php
    │       ├── front-page.php
    │       ├── functions.php        # Theme setup, menus, data, and asset loading
    │       ├── header.php
    │       ├── index.php
    │       ├── page.php
    │       ├── single.php
    │       ├── style.css            # WordPress theme header and generated styles
    │       └── theme.json           # WordPress design settings
    └── velvet-oak.zip               # The installable theme archive
Look Inside `style.css` and `functions.php`

If you open the generated style.css, you will see the WordPress theme header populated from your wp.config.ts. The output is a PHP-backed WordPress theme with generated HTML fragments and standard theme files; it is not a JavaScript server application.

Can I deploy directly via FTP, rsync, or CI/CD instead of uploading the ZIP manually?

Yes! When you run pnpm export, ForgeWP writes the complete, uncompressed theme directory directly to .forgewp/out/<theme-name>/. You can point your CI/CD pipeline, Git deployment action, or rsync script directly at this folder to push updates to your server automatically without having to unpack the ZIP file.

Step 2: Install and Activate in WordPress

Now that you have your compiled .zip file, installing it onto any WordPress site takes less than 30 seconds:

  1. Log in to your WordPress Admin dashboard (/wp-admin).
  2. In the left-hand navigation, navigate to Appearance > Themes.
  3. Click the Add New Theme button at the top of the page.
  4. Click Upload Theme.
  5. Click Choose File and select your generated theme ZIP:
Theme ZIP Path
my-theme/.forgewp/velvet-oak.zip
  1. Click Install Now.
  2. Once uploaded, click Activate.

Visit your WordPress site in your browser. The theme runs in WordPress using PHP; Node.js is not needed on the production server. Any client-side islands or block scripts in your theme still run in the visitor's browser.

Pre-Export Health Checks

Before creating a production export for a client or live site, it is best practice to run two diagnostic checks:

1. ForgeWP Doctor

Runs internal integrity checks across your configuration, templates, and WordPress mappings:

Terminal
pnpm forgewp doctor

2. TypeScript Typecheck

Ensures there are no TypeScript syntax errors or broken props in your components:

Terminal
pnpm typecheck

Useful Export Command Options

You can customize the export process using command-line flags:

Terminal
# Skip the Vite build if dist/ is already fresh
pnpm forgewp export --skip-build

# Output only the theme folder without generating a .zip archive
pnpm forgewp export --no-zip

# Validate the generated package and fail on validation warnings
pnpm forgewp export --validate --strict

What Export Does NOT Mean

To keep your mental model clear, remember:

  • Export does not replace your live database content: Your blog posts, pages, and media library still live safely inside WordPress. ForgeWP only provides the theme templates that display that content.
  • Export does not require Node.js on your server: The live WordPress host only needs standard PHP. Your visitors receive ultra-fast server-rendered HTML.
  • Export does not lock you into a proprietary format: If you ever deactivate ForgeWP, the exported theme is standard PHP and CSS that any WordPress developer can inspect.

You're All Set!

Congratulations! You have mastered the complete ForgeWP workflow:

  1. Checked your system requirements.
  2. Scaffolded a fresh theme using create-forgewp.
  3. Ran the instant local dev server with offline CMS simulation.
  4. Exported and installed a production-ready WordPress theme ZIP.

In Project Anatomy, we will explore each file and directory in depth to see how ForgeWP connects your React layouts to WordPress templates! Proceed to Project Directory Map.