Use this checklist before handing a theme to a client or applying an update. Documentation coverage, compiler validation, and live-site acceptance answer different questions. Record the checks you actually run for the theme and environment being released.

1. Check the development project

Use a Node version compatible with the installed dependency tree; see Requirements.
Run the theme's TypeScript check and pnpm forgewp doctor.
Confirm theme identity, public links, asset paths, form recipients, and locale settings.
List which content belongs to source, Page fields, blocks, site options, and plugins.
Review seeding before installation or updates. Disable unwanted post/product seeding and back up an existing site's database.

2. Check the export

Run pnpm forgewp export --validate --strict. Use a fresh build for a release; --skip-build deliberately reuses previous assets.

Table · 2 columns


Inspect	Expected result
Theme files	Required PHP wrappers, `style.css`, `theme.json`, assets, and expected Page/CPT templates exist.
Data bindings	Recognized WordPress placeholders become the intended PHP calls; live values are not accidentally fixed to preview data.
Gutenberg blocks	Expected block metadata, editor controls, render files, and nested-child settings are present.
Islands	Intended components have discoverable chunks and matching hydration wrappers.
Assets and fonts	Local files exist, URLs resolve from the installed theme, and any remote dependencies are intentional.
Custom PHP	PHP syntax checks pass on generated files and any appended server hooks.

A successful export validates the package; use the next steps to verify its behavior with WordPress.

3. Check WordPress rendering and editing

Install on a test site matching the target WordPress/PHP/plugin environment. Record versions and any required plugin setup.

Open the front page, a normal Page, a custom Page template, a single post, a CPT single/archive where used, search results, and a missing URL.
Change titles, body blocks, block attributes, Page fields, menus, and options used by the theme. Save, reload the editor, and check the frontend.
Confirm repeated block instances and separate Pages keep independent values.
Verify nested blocks allow the intended insertion, removal, and movement for the client's editor role.
Test empty fields, missing images, empty query results, real permalinks, and a subdirectory installation if the deployment uses one.
Check metadata and structured data with the site's active SEO plugin.

4. Check interactive and backend workflows

Test islands with pointer and keyboard, narrow screens, zoom, and reduced motion. Check focus restoration and console errors.
Verify important navigation/content with JavaScript disabled or delayed.
For forms, test invalid input, field errors, a valid submission, stored records when enabled, authorized admin access, and actual mail delivery.
Verify locale-specific labels, switched URLs, and each locale's client-owned form fields where used.
For advanced queries, test filter changes, empty results, pagination, and the production queryId contract.
Verify shortcodes and other plugin-specific output with the actual installed plugin.

5. Check an update against existing content

Make representative edits in WordPress first. Export a new theme version, replace the test theme, and verify those edits again. Check block validation messages, seed effects, removed/renamed fields, and any custom migrations. Keep the previous theme artifact and a database backup so rollback includes files and data when needed.

Record the evidence