Doc Category: Commands

Site Editor work — custom templates, template parts, user-created patterns, Global Styles, Font Library activations — lives in the WordPress database, not in your repo. Without a round-trip, that work is invisible to git, unreviewable, and lost when the site dies. rig:bake (shipped in WP Rig 3.5) closes the loop: it bakes database state into version-controlled theme files, then verifies and scrubs the database records.

Availability & requirements

• Paradigm: active for universal and block-based themes — classic themes refuse with guidance (exit 1).
• Requirements: Node 18+, WP-CLI 2.12+, writable active block theme.
• Origin: a Node port of bacoords/wp-theme-control by Brian Coords, pinned to an upstream SHA, with WP Rig-specific forks.

Commands

npm run rig:bake            # all scopes: fonts → templates → styles → patterns
npm run rig:bake:plan       # read-only inventory + collision report
npm run rig:bake:clean -- .wp-theme-control/runs/<run>/manifest.tsv
npm run rig:bake -- <scope> [flags]   # one scope + upstream flags passthrough

npm run rig:bake            # all scopes: fonts → templates → styles → patterns
npm run rig:bake:plan       # read-only inventory + collision report
npm run rig:bake:clean -- .wp-theme-control/runs/<run>/manifest.tsv
npm run rig:bake -- <scope> [flags]   # one scope + upstream flags passthrough

Passthrough flags: --path=, --url=, --user=, --state-dir=, --dry-run, --clean, --force.

What ships where

The safety model

Every write appends kind / record_id / slug / target / sha256 to a per-run manifest under .wp-theme-control/runs/ (gitignored), with backups per run. Cleanup is conservative by design: rig:bake:clean deletes only records whose exported files still match the manifest hash, only for the expected post type, and only while the pattern is still unsynced or the Global Styles post is unchanged. --force bypasses the hash check only. Each baked pattern file carries an idempotent Baked: yes header so lint tooling can recognize it.

Runtime URLs

Content that references local absolute URLs (your dev site’s uploads, theme assets) is rewritten in PHP — via wp eval, so WordPress’ own parse_blocks() semantics stay byte-identical — to the three sanctioned runtime expressions: get_stylesheet_directory_uri(), wp_get_upload_dir()['baseurl'], and home_url(). Anything else containing PHP syntax is refused.

The user-styles overlay (SPEC-016)

Baked Global Styles and font activations never write theme.json directly — rig:tokens is the sole theme.json writer and would clobber them. Instead they land in config/user-styles.json, a git-tracked overlay that the tokens generator merges last:

• Objects deep-merge; arrays replace wholesale.
• Fonts collapse — custom definitions win on duplicate slugs.
• SSOT keys (version, $schema, settings.viewport, settings.blockVisibility, isGlobalStylesUserThemeJSON) never merge.
• Regeneration is deterministic: two rig:tokens runs after a bake are byte-identical.
• The PHP runtime is overlay-blind — it is a build-time input only, guarded by a PHPUnit parity test.

The usage loop

git status                        # must be clean — a bake is reviewed as a diff
npm run rig:bake:plan             # inventory + collisions (writes nothing)
npm run rig:bake                  # writes files; does NOT clean the DB
npm run lint:patterns && npm run lint:blocks && npm run lint:css
git add -p && git commit          # review the diff
npm run rig:bake:clean -- .wp-theme-control/runs/<run>/manifest.tsv

git status                        # must be clean — a bake is reviewed as a diff
npm run rig:bake:plan             # inventory + collisions (writes nothing)
npm run rig:bake                  # writes files; does NOT clean the DB
npm run lint:patterns && npm run lint:blocks && npm run lint:css
git add -p && git commit          # review the diff
npm run rig:bake:clean -- .wp-theme-control/runs/<run>/manifest.tsv

The bake is a review-first workflow: nothing leaves the database until you have read the diff and committed it.

Lint integration for baked files

Patterns marked Baked: yes keep their Title/Slug/Categories and markup-validity checks but get a tolerance profile: scaffold-placeholder content downgrades to a warning, and hidden runtime patterns get a Categories warning. The three sanctioned runtime-URL PHP expressions are neutralized in block-comment attributes — any other PHP still fails lint:patterns.

Known boundaries

• Synced patterns are not migrated; distribution packaging, localization, Media Library moves, and remote SSH targets are upstream boundaries, inherited.
• The overlay never carries PHP expressions — local absolute URLs in captured styles are flagged (report-only), and media belongs in block markup instead.
• Baked font families replace the token-derived fontFamilies list in editor presets (the user layer wins) — see Font Management.
• Font asset files survive clean for recoverability; the overlay is removed with the styles/fonts clean.

Related reading

Pair this with Design Tokens v2 (the merge contract), Font Management (the fonts boundary), and Theme Paradigms (why this is gated to block-capable themes).

Every WP Rig workflow runs through npm/Bun scripts (plus a few Composer and WP-CLI commands). This is the canonical command reference — the same list lives in the repo at docs/commands.md, and npm run with no arguments lists everything available in your checkout.

Development & build

Initialization & setup

Quality & linting

Design tokens

See Design Tokens v2 for the full system.

WordPress blocks

Component registry

Full lifecycle docs: The Open Component Registry.

Site Editor bake & sync

Full workflow docs: Site Editor Bake & Sync.

Patterns, testing, audits

• npm run rig:pattern — scaffold a block pattern with i18n-aware headers + config-seeded categories.
• npm run rig:localize — generate the .pot translation file in languages/.
• npm run test:e2e — full Playwright suite (chromium + firefox + webkit).
• npm run test:e2e:spatial — spatial & visual regression (deterministic geometry checks).
• npm run test:e2e:screenshot — capture/update regression screenshots.
• npm run test:scripts — Jest unit tests for build tooling.
• npm run test:prod-build — full production-bundle verification.
• npm run audit:theme-review (and the other audit:* commands) — WordPress.org-style theme review checks.

Composer & WP-CLI

• Testing: composer test:unit, test:integration, test:all (unit + integration + PHPStan).
• Quality: composer phpstan, composer phpcs-dev, composer fix (Rector + PHP-CS-Fixer + PHPCBF).
• Environment: composer setup-wp-tests, composer install-codestandards.
• WP-CLI: wp rig test-setup and wp rig import-test-data set up the Theme Unit Test environment.

The Open Component Registry (OCR, shipped in WP Rig v3.4) is a federated ecosystem for sharing performant, agent-ready theme components. Instead of copy-pasting feature code between projects, you search a registry of verified components, add them with one command, and pull framework-level updates later without losing your customizations.

Why a component registry

Every registry component ships with more than code: a manifest.json declaring its assets and paradigm, a SPEC.md with its technical contract, and a SKILL.md with implementation recipes. That makes components both performance-verified (scored, with conditional asset loading) and agent-ready (AI tools can read the same docs you do).

The component lifecycle

Adding your first component

Before building a feature from scratch, check whether a verified component already exists:

npm run rig:search related-posts
npm run rig:add related-posts

npm run rig:search related-posts
npm run rig:add related-posts

When choosing, prefer components with a performance score of 95+ and the Agent-Ready badge (meaning SPEC.md and SKILL.md ship with the component). After adding, the component docs land in .ai/skills/ — read them (or let your AI assistant read them) before wiring the component into templates.

The manifest and scoped assets

Manifest v2 requires a paradigm field matching the component PARADIGM constant, and supports scoped assets: an asset_mapping entry marked scoped: true is compiled into the theme pipeline but enqueued conditionally by the component own PHP — a block component never adds global CSS to pages that do not use it. Components build through the same Bun/Lightning/esbuild pipeline as core theme assets: no extra HTTP requests, no separate build config.

Paradigm-aware components

A component that serves only one theme-dev paradigm declares it and uses the trait — the theme class skips inactive components automatically during discovery:

// inc/My_Feature/Component.php
class Component implements Component_Interface {
	use Paradigm_Component_Trait;
	const PARADIGM = 'block-based';
	public static function is_active(): bool {
		return self::paradigm_active();
	}
}

// inc/My_Feature/Component.php
class Component implements Component_Interface {
	use Paradigm_Component_Trait;

	const PARADIGM = 'block-based';

	public static function is_active(): bool {
		return self::paradigm_active();
	}
}

Bundled patterns/ directories inside a component are registered by the inc/Block_Patterns component in block-capable themes.

Contributing a component

• Scaffold the structure: npm run create-rig-component "My Feature" --templating --tests — it generates Component.php, manifest.json, SPEC.md, and SKILL.md registry-ready by default.
• Implement the feature and keep everything inside the component directory under inc/.
• Validate locally: npm run rig:test-component my-feature.
• Package and submit: npm run rig:prepare my-feature — it produces exactly what the GitHub PR needs.

Updates are “starter” semantics: after rig:add, the code is yours to modify. rig:update later pulls upstream fixes with a diff-based merge, preserving local customizations.

Private and team registries

The registry is federated: organizations can point a theme at their own GitHub-backed registry (via the inc/Registry_Config component) to serve a private set of curated components alongside the public one — useful for agencies maintaining vetted in-house features.

Related reading

See Theme Paradigms for the gating model, Building Custom Blocks for block components, and WP Rig Node Scripts for the full rig:* command reference.