Performance & the Asset Pipeline

WP Rig’s asset pipeline is built around one goal: ship the smallest possible payload with the fewest requests, without asking you to think about it. This post covers the loading strategies, the manifest system that powers them, the modern image pipeline, and how to measure the results.

Critical CSS: the cookie-based “best of both worlds” strategy

Above-the-fold CSS is the classic performance dilemma: inline it and every page load carries the payload, or link it and pay a render-blocking round trip. WP Rig does both, conditionally:

First visit: critical CSS is inlined into a <style> tag in the <head> for the fastest possible First Contentful Paint.
Subsequent visits: once the browser has cached the full stylesheets (detected via the wprig_critical_cached cookie), the theme enqueues them as standard external files — shrinking the HTML payload instead.

The Asset_Provider manifest system

Every component declares its assets in a manifest instead of hand-wiring enqueues. Components implement the Asset_Provider interface and return a manifest; a strategy key opts an asset into a loading strategy:

public function get_asset_manifest(): array {
	return array(
		'styles' => array(
			'my-critical-section' => array(
				'file'     => 'section.critical.min.css',
				'strategy' => 'cookie-critical',
			),
		),
	);
}

public function get_asset_manifest(): array {
	return array(
		'styles' => array(
			'my-critical-section' => array(
				'file'     => 'section.critical.min.css',
				'strategy' => 'cookie-critical',
			),
		),
	);
}

The cookie-critical strategy is registered by default in the Performance component — any CSS file ending in .critical.css is a candidate for inlining.
Custom strategies: implement the Critical_Strategy_Interface and register your own.
The Fonts component rides the same system: localized font CSS is marked for inlining automatically.
Navigation scripts use the manifest-driven performance system — async/defer by default.

Interaction-delayed JS loading

Non-essential JavaScript doesn’t load until the user actually interacts with the page. A tiny bootloader prints with the HTML and defers script loading until the first touchstart, mousemove, scroll, keydown, or click — so initial render never competes with JS parsing. Combined with critical-CSS inlining, this is what makes WP Rig themes score well on TBT (Total Blocking Time) out of the box.

Modern image pipeline: WebP + AVIF

Images in assets/images/src are optimized by sharp/libvips (scripts/tasks/images.js) at build time:

JPEG/PNG sources additionally emit WebP (universal baseline, quality 75) and AVIF — the WordPress 7.1-era default, encoded via heif({ compression: 'av1' }), including 10-bit/HDR-capable output.
HEIC/HEVC is deliberately not a target (Safari-only and patent-encumbered).
If a host sharp build lacks the AV1 codec, AVIF is skipped with a warning and WebP still ships — one missing codec never breaks the build.

Precompiled block manifests

Registering theme blocks by scanning directories and parsing every block.json on every request is wasted work. WP Rig generates a precompiled blocks-manifest.php and registers blocks with the WordPress 6.7/6.8 batch APIs — wp_register_block_types_from_metadata_collection() (or wp_register_block_metadata_collection() on earlier versions) — eliminating runtime filesystem scanning entirely while staying 100% backward compatible.

Server-side caching

Component discovery in Theme.php is cached in a static per-request and augmented with transient-based caching for configuration retrieval and asset loading.
The dev toolbar’s Purge Cache button (see WP Rig Tools) clears WordPress transients and local asset caches in one click — use it when you’ve changed config and want to see the effect immediately.

Fonts

Font delivery has its own post: automatic preloading, font-display: block FOUT prevention, and inlining through Asset_Provider — see Font Management.

Measuring: Lighthouse CI

The pipeline is auditable. With your local environment running:

npm run test:perf          # collect (3 runs/page) + assert + upload report
npm run test:perf:collect   # collection only
npm run test:perf:report    # open the HTML report

npm run test:perf          # collect (3 runs/page) + assert + upload report
npm run test:perf:collect   # collection only
npm run test:perf:report    # open the HTML report

Budgets live in .lighthouserc.cjs at the theme root (it auto-resolves your local proxyURL); tune largest-contentful-paint, cumulative-layout-shift, total-blocking-time, and category scores per project. When interpreting results on WordPress: disable plugins to establish a theme baseline, and mind that image handling in templates moves LCP/CLS as much as CSS does.

Font Management (preload + FOUT), Modern CSS with Lightning CSS (the CSS side of the pipeline), Building Custom Blocks (block manifests in depth), and WP Rig Tools (the purge-cache button).