ForgeWP

Install and Verify the Theme in WordPress

Install an exported theme, verify editing and visitor behavior, and update an existing site while checking saved content and seed settings.

Finish your release workflow by installing the exported files in WordPress. Export validation checks the package; WordPress verification covers real content, permissions, plugins, and the editor experience.

Start on a staging site: a separate WordPress installation used to test a release before changing the public site. For updates, use a recent copy of the site's content and relevant plugin configuration.

Before installing

  1. Complete Export and Validate.
  2. Check Requirements, including WordPress 6.6 or newer for generated theme.json v3 settings. Confirm the PHP and plugin requirements of the specific project.
  3. Locate .forgewp/<theme-slug>.zip in the source project. The slug is the generated directory/archive name, such as alpine-resort.
  4. Review seed in wp.config.ts. Generated routines can create or update database records; see the update section below.
  5. Back up an existing site's database, uploads, and theme files. Keep the previous working theme package.

Node.js is needed on the machine that builds the theme, not on the WordPress production server. Image optimization happens during export; production PHP does not run the Sharp build pipeline.

Choose your target WordPress version

Check both the generated style.css header and the requirements of the features used by your theme. Use the newer requirement as your starting point, then verify the theme on your target version.

Install using the WordPress dashboard

  1. Log in to the staging site's dashboard.
  2. Open Appearance > Themes > Add New Theme > Upload Theme. Labels can vary slightly by WordPress version.
  3. Select .forgewp/<theme-slug>.zip and click Install Now.
  4. If replacing an installed version, review WordPress's replacement screen before proceeding.
  5. Activate the theme on staging. Activation may run generated setup and seeding hooks.
  6. Confirm the intended homepage under Settings > Reading, assign navigation menus, and check Page template selections.

If the archive exceeds the host's upload limit, adjust the limit through the host or use its supported deployment method. Uploading the ZIP does not upload your local Node.js toolchain.

Optional: install using WP-CLI

WP-CLI is a separate command-line tool for administering WordPress. These commands run on the WordPress host, where WP-CLI is installed, from the WordPress installation directory. They differ from local pnpm forgewp commands.

Transfer the exported ZIP to the host, then replace the example path with its location there:

WordPress host: install and activate on staging
wp theme install /path/to/alpine-resort.zip --activate

To replace files of an already installed version:

WordPress host: replace the installed theme on staging
wp theme install /path/to/alpine-resort.zip --force --activate

Here, --force tells WP-CLI to replace theme files. It is not ForgeWP's database seed --force option.

Verify the visitor's site

Match the checklist to the features your theme uses. Inspect the asset filenames produced by your export and check islands on pages that include interactive components.

Table · 3 columns
Check
How to verify
Expected result
Homepage and Page templates
Open the homepage and a Page using each template
Correct layout, current Page data, and intended title behavior
Posts and archives
Open a post and relevant post-type/category archives
Correct content, queries, links, and empty states
Missing pages
Visit an unknown URL
The intended 404 response and layout
Assets
Inspect browser developer tools: Console and Network
Required images, styles, fonts, and scripts load without relevant errors
Responsive layout
Check narrow and wide screens
Readable content and usable navigation
Menus
Assign menus to theme locations, then follow links
Expected links and submenu behavior
Interactive components
Use drawers, dialogs, filters, and other controls
Correct behavior after the configured hydration trigger
Forms, if included
Submit valid and invalid entries
Intended validation, storage, and notifications
Plugin content
Test the exact blocks, shortcodes, and integrations used
Output appears in the intended slot and works on the frontend

For fonts and images, inspect actual requests. Local font files and optimized variants depend on the export inputs and pipeline results.

Verify the editor's experience

Use an account with the permissions the client will have. An administrator may see additional controls.

  1. Open a test Page and choose its intended template.
  2. Change a declared page field. Save, reload the editor, and check the visitor page.
  3. Insert a theme Gutenberg block. Change its attributes, save, reload, and check its frontend output.
  4. Reorder or remove sections if permitted. Check nested-block restrictions and allowed child types.
  5. Test core and plugin blocks inside <BlockArea />, or on the ForgeWP Builder canvas when that is the intended page model.
  6. Explain how clients edit fields and compose blocks, and how developers maintain the surrounding layouts.

ForgeWP Builder provides a page canvas for Gutenberg content, using WordPress's native block editor. See Content Ownership and Editability.

Inspect an interactive island

An island is a region where browser JavaScript enables interaction. Inspect its wrapper in the browser Elements panel. A wrapper can look like this; names, triggers, props, and styles vary:

Example generated island wrapper
1<div
2  data-forgewp-hydrate="mobile-nav"
3  data-forgewp-trigger="visible"
4>
5  <!-- Initial component markup -->
6</div>

Inspect runtime configuration when present:

Browser Console: inspect generated hydration configuration
1window.forgeWpHydration

Use the Network panel and test the control itself. Inspect request timing alongside the configured trigger, preloads, shared chunks, and caching.

Update an existing site

Keep client content connected across releases by maintaining stable block attributes and metadata keys. Review generated setup and seed routines alongside template changes so the update follows your intended content policy.

Keep saved-data contracts stable

Table · 2 columns
Change
What to consider
Rename a block
Existing posts reference its old registered name; retain compatibility or migrate them
Rename an attribute or meta key
Existing values remain under the old name; provide a fallback or migration
Change a field's value type
Old values may no longer match the renderer or controls
Change a default
Check saved values and missing values separately; a new default is not a migration
Remove a content slot
Saved content may remain in the database while disappearing from the page
Replace a template
Verify existing Pages still select a valid template and render their content

Review database seeding

Seeding copies development content into WordPress. It is useful for first installation, but differs from deploying presentation changes.

The generated mock-content seeder can run on activation and admin_init (an admin request), subject to its guards:

  • once uses a saved seed marker and skips matching existing posts unless forced.
  • upsert can update matching posts by slug when seed data changes, including content and supplied custom fields. It does not merge client edits.
  • force mode can repeatedly write seed values when the routine runs and guards permit it.
  • developmentOnly: true checks WP_DEBUG; it does not independently detect a production hostname.
  • The generated seed command's --force flag bypasses the development guard and seed/hash checks.

For releases that should not seed mock posts or products, disable those seeders before exporting:

wp.config.ts: merge into the existing configuration
1seed: {
2  mockData: false,
3  products: false,
4  developmentOnly: true,
5}

This snippet configures those seeders; other setup hooks, plugins, or custom migrations may still write to the database. See Database Seeding Strategies.

Rehearse the release

  1. Use a staging copy of the live site, or install the old theme with representative saved content.
  2. Record a few client-edited values and block compositions.
  3. Install the new package and repeat the visitor/editor checks. Open the admin too, so enabled admin-time routines can run.
  4. Confirm the recorded values still exist and display correctly.
  5. Deploy the same verified package through the host's release process. Clear relevant caches and repeat a short smoke test.
  6. If needed, restore the previous package. If the release changed data, file rollback alone may be insufficient; use the tested migration or database recovery plan.

Avoid replacing the live database with an older staging copy: that can overwrite newer content. Use your host's release-directory process where available, and include content compatibility and rollback checks in the release plan.

Troubleshooting installation

Table · 2 columns
Symptom
First checks
ZIP rejected
Confirm this is the generated ZIP and inspect its theme directory and style.css
Blank page or fatal error
Read the PHP error log; check the actual error, PHP version, plugins, and custom code
Missing assets
Inspect failed URLs and deployed files; check caching and HTTPS configuration
Inert interactive component
Inspect Console errors, wrappers, runtime configuration, and script responses
Missing block
Check exported block files, registration, inserter restrictions, and permissions
Missing template
Check the active package, generated template header, and Page template selection
Missing content
Check the template, Page context, data bindings, and whether it renders the saved body

Fix generated behavior in the maintained source and export again. A fix made only in .forgewp/out/ can disappear on the next export.

Next steps

Keep the source revision, lockfile, package, and verification notes for each release. Continue to Compiler Engine and Architecture for implementation details.