If you built WordPress themes between 2018 and 2021, you almost certainly crossed paths with WP Rig. It was the build-tool-meets-starter-theme that promised a performance-first workflow at a time when most theme developers were still enqueuing monolithic stylesheets and hoping for the best. Then the block editor arrived, Full Site Editing matured, and a wave of new tooling, Create Block Theme, the theme.json specification, the Styles API, seemed to push WP Rig into the background.
Except it never actually went away. And in 2026, with block theme development demanding a serious front-end build pipeline more than ever, WP Rig is quietly making a comeback among developers who want the best of both worlds: the modern block theme architecture and an optimized, automated development workflow underneath it.
This guide covers everything you need to know, what WP Rig does, why it matters again, how it compares to the alternatives, and how to set it up for a modern block theme project today.
A Brief History of WP Rig
WP Rig was created by Morten Rand-Hendriksen and a team of contributors as an open-source project under the WordPress community umbrella. The original pitch was simple but powerful: give theme developers a modern build process, Gulp, Babel, PostCSS, BrowserSync, pre-configured and ready to go, wrapped inside a starter theme that followed WordPress coding standards to the letter.
What set WP Rig apart from other starter themes at the time (Underscores, Sage, Flavor) was its laser focus on front-end performance. Out of the box, WP Rig delivered:
- CSS code splitting by template, only the styles needed for the current template loaded on the page
- Lazy loading for images and iframes, before browsers had native lazy loading
- Progressive loading of CSS, critical styles inline, non-critical deferred
- Service worker support, enabling offline-first experiences
- ES module bundling with Babel, write modern JavaScript, ship backward-compatible code
For a couple of years, WP Rig was arguably the most sophisticated WordPress theme development toolkit available. LinkedIn Learning built an entire course around it. Conference talks featured it. Agencies adopted it as their internal starter.
Then Full Site Editing (FSE) landed, and the conversation shifted entirely to theme.json, block templates, and template parts. WP Rig’s PHP-template-based architecture suddenly looked like a relic. Activity on the GitHub repo slowed. Stars kept accumulating, developers bookmarked it, but active development stalled.
Why WP Rig Is Relevant Again in 2026
Here is the thing that gets lost in the block-theme-or-bust narrative: block themes still need a build process. They still need CSS compilation, JavaScript bundling, image optimization, and a local development server. The theme.json file handles design tokens and block styles beautifully, but it does not replace a front-end build pipeline.
If you are building a production-grade block theme, something beyond a child theme or a simple variation, you need tooling. And that is exactly what WP Rig provides.
Block themes solved the template problem. WP Rig solves the build problem. They are not competing, they are complementary.
Several developments have converged to make WP Rig useful again:
1. Block Themes Have Gotten More Complex
Early block themes were intentionally minimal, Twenty Twenty-Two was barely more than a theme.json file and a handful of HTML templates. But real-world block themes in 2026 include custom block styles, interactive view scripts, complex pattern libraries, custom fonts with variable weight subsetting, and significant CSS beyond what theme.json can express. This complexity demands a build step.
2. Performance Standards Have Risen Sharply
Google’s Core Web Vitals are no longer optional knowledge. Clients expect sub-2-second LCP. They expect zero CLS. They expect passing scores not just on desktop but on mobile with throttled connections. WP Rig’s code-splitting, critical CSS inlining, and asset optimization pipeline deliver measurable improvements that manual block theme development often misses.
3. The Developer Experience Gap
WordPress core ships wp-scripts for block development, but its theme support is minimal. Create Block Theme is a plugin for exporting themes from the editor, it is not a development framework. There is a gap between “I have a theme.json file” and “I have a production-ready theme with optimized assets, linting, automated testing, and hot reloading.” WP Rig fills that gap.
WP Rig vs Create Block Theme vs Starting from Scratch
Before diving into setup, it helps to understand where WP Rig sits in the current landscape. Each approach has distinct strengths and trade-offs.
| Feature | WP Rig | Create Block Theme | theme.json from Scratch |
|---|---|---|---|
| Build pipeline | Full (Gulp, PostCSS, Babel, BrowserSync) | None (editor-based export) | DIY (webpack, Vite, or wp-scripts) |
| CSS code splitting | Automatic by template | Not available | Manual configuration |
| Performance optimization | Built-in (critical CSS, lazy loading, service workers) | Basic (depends on core defaults) | Manual implementation |
| Block theme support | Requires adaptation (fork + modify) | Native (designed for block themes) | Native |
| theme.json integration | Add manually or via community forks | Full editor-to-file sync | Full manual control |
| Hot reloading | BrowserSync built in | Not available | Depends on your toolchain |
| Learning curve | Moderate (Node.js, Gulp, PostCSS knowledge helps) | Low (visual, no CLI) | High (everything from scratch) |
| Best for | Performance-critical custom themes | Quick prototyping, client handoffs | Full control, experienced developers |
The key insight: these tools are not mutually exclusive. You can use Create Block Theme to prototype a design in the editor, export it, then bring those templates and theme.json settings into a WP Rig project for production optimization. Many developers are doing exactly this in 2026.
Setting Up WP Rig for a Modern Block Theme Project
Let us walk through a practical setup. The goal is to take WP Rig’s build pipeline and adapt it for a block theme that uses theme.json, HTML templates, and block patterns.
Step 1: Clone and Configure
Start by cloning the WP Rig repository. The most actively maintained fork for block theme compatibility is on GitHub, search for forks that have been updated in the last year, as the original repo’s last official release predates FSE.
git clone https://github.com/wprig/wprig.git my-block-theme
cd my-block-theme
npm installAfter installation, open the config/config.default.json file and update your local development URL, theme slug, and other project-specific settings. This file drives BrowserSync and the entire build process.
Step 2: Add the Block Theme Structure
WP Rig’s default file structure assumes classic PHP templates. For a block theme, you need to add the required directories alongside the existing structure:
my-block-theme/
├── block-templates/ # Block theme HTML templates (new)
│ ├── index.html
│ ├── single.html
│ ├── archive.html
│ ├── page.html
│ ├── 404.html
│ └── search.html
├── block-template-parts/ # Reusable template parts (new)
│ ├── header.html
│ ├── footer.html
│ └── sidebar.html
├── patterns/ # Block patterns (new)
│ ├── hero-banner.php
│ ├── featured-posts.php
│ └── call-to-action.php
├── theme.json # Design tokens and settings (new)
├── style.css # Theme header + minimal base styles
├── assets/
│ ├── css/
│ │ └── src/ # Source CSS (PostCSS)
│ └── js/
│ └── src/ # Source JavaScript (ES modules)
├── dev/ # WP Rig build configuration
└── gulp/ # Gulp task definitionsThe key is keeping WP Rig’s asset pipeline (the assets/, dev/, and gulp/ directories) intact while layering the block theme structure on top. The PHP template files in WP Rig’s default structure become fallbacks, WordPress will prioritize the block templates when they exist.
Step 3: Configure theme.json
Your theme.json file becomes the single source of truth for design tokens. Here is a production-ready starting point:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"color": {
"palette": [
{ "slug": "primary", "color": "#1a365d", "name": "Primary" },
{ "slug": "secondary", "color": "#2d3748", "name": "Secondary" },
{ "slug": "accent", "color": "#ed8936", "name": "Accent" },
{ "slug": "background", "color": "#ffffff", "name": "Background" },
{ "slug": "foreground", "color": "#1a202c", "name": "Foreground" }
],
"custom": false,
"defaultPalette": false
},
"typography": {
"fontFamilies": [
{
"fontFamily": "'Inter', sans-serif",
"slug": "body",
"name": "Body",
"fontFace": [
{
"fontFamily": "Inter",
"fontWeight": "300 900",
"fontStyle": "normal",
"fontDisplay": "swap",
"src": ["file:./assets/fonts/inter-variable.woff2"]
}
]
}
],
"fluid": true,
"fontSizes": [
{ "slug": "small", "size": "0.875rem", "fluid": { "min": "0.813rem", "max": "0.875rem" } },
{ "slug": "medium", "size": "1rem", "fluid": { "min": "0.938rem", "max": "1rem" } },
{ "slug": "large", "size": "1.5rem", "fluid": { "min": "1.25rem", "max": "1.5rem" } },
{ "slug": "x-large", "size": "2.25rem", "fluid": { "min": "1.75rem", "max": "2.25rem" } }
]
},
"spacing": {
"units": ["rem", "em", "px", "vh", "vw"],
"spacingScale": { "steps": 7 }
},
"layout": {
"contentSize": "740px",
"wideSize": "1100px"
}
}
}The important detail here is that your theme.json design tokens should align with the CSS custom properties that WP Rig’s PostCSS pipeline generates. This means your source CSS files can reference the same color values, spacing scales, and typography settings that the editor uses, keeping the front end and back end in perfect sync.
Step 4: Update the Gulp Pipeline
WP Rig’s Gulp configuration needs a few modifications to handle the block theme structure. Open the Gulp task files and add watch targets for your new directories:
- Watch block templates and parts, add
block-templates/**/*.htmlandblock-template-parts/**/*.htmlto the BrowserSync watch list for live reload - Watch patterns, add
patterns/**/*.phpto trigger reload when pattern files change - Watch theme.json, changes to design tokens should trigger both a CSS rebuild and a browser reload
- Update the build task, ensure the production build copies block templates, template parts, patterns, and theme.json to the distribution folder
These are straightforward additions, usually just a few lines in the existing Gulp configuration files. The core asset pipeline (CSS compilation, JavaScript bundling, image optimization) stays exactly the same.
The Performance Case: What WP Rig Actually Delivers
Let us get specific about the performance benefits, because vague claims about “optimization” do not help anyone make decisions.
CSS Code Splitting
This is WP Rig’s headline feature, and it is genuinely impressive. Instead of loading a single monolithic stylesheet on every page, WP Rig splits your CSS by template. The archive page only loads archive styles. The single post page only loads single post styles. Shared styles load everywhere; template-specific styles load conditionally.
In a typical block theme with 40-60KB of total CSS, code splitting can reduce per-page CSS payload by 30-50%. That translates directly to faster First Contentful Paint and improved LCP, especially on mobile connections where every kilobyte matters.
Critical CSS Inlining
WP Rig identifies above-the-fold styles and inlines them directly in the <head>, then loads the remaining CSS asynchronously. This eliminates render-blocking stylesheets, one of the most common performance bottlenecks in WordPress themes. Combined with code splitting, you get a page that renders its initial viewport almost instantly while the rest of the styles load in the background.
JavaScript Module Loading
WP Rig uses Babel to transpile modern ES module syntax into backward-compatible code, but it also supports differential loading, serving ES modules to modern browsers and legacy bundles to older ones. In 2026, with browser support for ES modules above 97%, you can often skip the legacy bundle entirely and ship smaller, faster JavaScript.
Image Optimization
The build pipeline includes image compression for theme assets (not user uploads, which WordPress handles separately). SVGs get optimized, PNGs get compressed, and the output is measurably smaller than what most developers commit to their repositories.
Performance is not a feature you add at the end. It is an architecture decision you make at the beginning. WP Rig makes that decision for you.
Customizing WP Rig for Full Site Editing
Adapting WP Rig for FSE requires understanding which parts of the framework are template-layer concerns (which FSE replaces) and which are build-layer concerns (which FSE does not touch).
What You Keep
- The entire Gulp-based build pipeline
- PostCSS processing with custom plugins and autoprefixing
- JavaScript bundling and transpilation
- BrowserSync for local development
- Image optimization tasks
- CSS code splitting logic (adapted for block templates instead of PHP templates)
- Linting configurations (ESLint, Stylelint, PHPCS)
What You Replace
- PHP template files (index.php, single.php, etc.) → replaced by block templates in
block-templates/ - Template parts via
get_template_part()→ replaced by HTML template parts inblock-template-parts/ - Customizer settings → replaced by theme.json and the Styles interface in the editor
- PHP-based navigation menus → replaced by the Navigation block
What You Add
- theme.json, design tokens, block settings, style variations
- Block patterns, reusable layout components in the
patterns/directory - Style variations, alternative theme.json files for different color schemes or typography presets
- Block styles, custom visual variants for core blocks, registered via PHP and styled via your PostCSS pipeline
- Interactive view scripts, using WordPress’s Interactivity API for dynamic front-end behavior
Integrating theme.json with WP Rig’s Asset Pipeline
This is where the real power emerges. WP Rig’s PostCSS pipeline can be configured to consume your theme.json design tokens, ensuring that your hand-written CSS and your editor-defined styles are always in sync.
Approach 1: CSS Custom Properties Bridge
WordPress automatically generates CSS custom properties from your theme.json settings. For example, a color palette entry with the slug “primary” becomes --wp--preset--color--primary. You can reference these custom properties directly in your PostCSS source files:
/* In your PostCSS source file */
.site-header {
background-color: var(--wp--preset--color--primary);
padding: var(--wp--preset--spacing--40);
}
.entry-content a {
color: var(--wp--preset--color--accent);
text-decoration-thickness: 2px;
text-underline-offset: 0.2em;
transition: color 0.2s ease;
}
.entry-content a:hover {
color: var(--wp--preset--color--secondary);
}This approach is simple and works immediately. Your CSS uses the same tokens the editor uses. When you update a color in theme.json, it changes everywhere, in the editor, on the front end, and in your custom CSS.
Approach 2: PostCSS Plugin for theme.json
For more advanced workflows, you can write a small PostCSS plugin that reads your theme.json at build time and makes the values available as PostCSS variables. This gives you access to theme.json values during compilation, useful for calculations, media queries, and other contexts where CSS custom properties are not supported.
// postcss-theme-json.js, A simple PostCSS plugin
const fs = require('fs');
const path = require('path');
module.exports = () => {
const themeJson = JSON.parse(
fs.readFileSync(path.resolve(__dirname, '../theme.json'), 'utf8')
);
return {
postcssPlugin: 'postcss-theme-json',
Declaration(decl) {
// Replace $theme(color.primary) with actual value
if (decl.value.includes('$theme(')) {
decl.value = decl.value.replace(
/\$theme\(([^)]+)\)/g,
(match, keyPath) => {
return resolveThemeValue(themeJson, keyPath);
}
);
}
}
};
};
module.exports.postcss = true;This is optional and adds complexity, but for large themes with dozens of design tokens, it creates a very clean development experience.
Building Block Patterns with WP Rig
Block patterns are the backbone of modern WordPress design. They are reusable layout components that content editors can insert and customize. WP Rig’s build pipeline adds value here in two ways:
- Pattern-specific CSS, If you follow WP Rig’s code-splitting conventions, styles for a pattern can be conditionally loaded only when that pattern is used on a page. This prevents unused pattern styles from bloating your stylesheet.
- Pattern-specific JavaScript, Interactive patterns (accordions, tabs, carousels) can have their scripts bundled separately and loaded on demand.
Here is a practical example of a pattern file that works within a WP Rig project:
<?php
/**
* Title: Hero Banner with CTA
* Slug: my-theme/hero-banner
* Categories: featured, banner
* Keywords: hero, banner, call to action
* Viewport Width: 1400
*/
?>
<!-- wp:cover {"dimRatio":50,"overlayColor":"primary","isUserOverlayColor":true,"align":"full"} -->
<div class="wp-block-cover alignfull">
<span class="wp-block-cover__background has-primary-background-color has-background-dim"></span>
<div class="wp-block-cover__inner-container">
<!-- wp:heading {"textAlign":"center","level":1,"fontSize":"x-large"} -->
<h1 class="wp-block-heading has-text-align-center has-x-large-font-size">Your Headline Here</h1>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center","fontSize":"large"} -->
<p class="has-text-align-center has-large-font-size">Supporting text that describes the value proposition.</p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons">
<!-- wp:button -->
<div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Get Started</a></div>
<!-- /wp:button -->
</div>
<!-- /wp:buttons -->
</div>
</div>
<!-- /wp:cover -->Community Forks and Contributions
The original WP Rig repository has not seen an official release in some time, but the community has kept the project alive through forks and contributions. Several notable directions have emerged:
- Vite-based forks, Some developers have replaced Gulp with Vite for faster build times and native ES module support. Vite’s hot module replacement is significantly faster than BrowserSync for CSS changes.
- Block theme forks, Dedicated forks that strip out the classic PHP templates entirely and restructure the project around block templates from the ground up.
- Tailwind CSS integration, Forks that replace PostCSS with Tailwind CSS while keeping WP Rig’s code-splitting and optimization logic intact.
- wp-scripts hybrid, Projects that combine WordPress’s official
@wordpress/scriptspackage with WP Rig’s theme-specific build tasks, getting the best of both ecosystems.
If you are evaluating WP Rig today, spend some time exploring the fork network on GitHub. The most active forks often have better documentation and more recent compatibility updates than the original repository.
Practical Getting Started Guide
Here is a condensed, step-by-step workflow for starting a new block theme project with WP Rig in 2026:
Phase 1: Foundation (Day 1)
- Clone WP Rig (or a maintained fork with block theme support)
- Run
npm installand verify the build works withnpm run build - Update
config/config.default.jsonwith your local development URL and theme slug - Create the
block-templates/,block-template-parts/, andpatterns/directories - Create a minimal
theme.jsonwith your color palette, typography, and spacing settings - Add a basic
block-templates/index.htmlthat references your template parts - Run
npm run devand confirm BrowserSync opens your site with the block theme active
Phase 2: Design System (Days 2-3)
- Define your complete color palette, typography scale, and spacing scale in theme.json
- Create PostCSS source files in
assets/css/src/that reference theme.json custom properties - Build your core block styles, customize the appearance of paragraphs, headings, lists, images, buttons, and other frequently used blocks
- Create style variations if your theme will offer multiple color schemes
- Register any custom block styles via PHP (e.g., a “shadow” variant for the Group block)
Phase 3: Templates and Patterns (Days 4-7)
- Build out all your block templates, home, single, page, archive, search, 404
- Create reusable template parts for header, footer, sidebar, and any other repeated sections
- Develop your pattern library, aim for 10-20 patterns covering common layout needs (hero sections, feature grids, testimonials, pricing tables, CTAs)
- Test every pattern in the editor to ensure they are easy to customize
- Add pattern categories and keywords for discoverability
Phase 4: Optimization and Testing (Days 8-10)
- Run the production build (
npm run build) and audit the output, check file sizes, verify code splitting is working - Test with Lighthouse, WebPageTest, and Chrome DevTools Performance panel
- Verify the theme passes the WordPress Theme Check plugin
- Test in the Site Editor, ensure all templates and patterns are editable without issues
- Test across browsers and devices, paying special attention to mobile performance
- Run accessibility checks, keyboard navigation, screen reader compatibility, color contrast
When WP Rig Is Not the Right Choice
Honesty is important. WP Rig is not the right tool for every project:
- Simple child themes or style variations, If you are only customizing colors, fonts, and spacing, theme.json alone is sufficient. You do not need a build pipeline.
- Quick client projects with tight budgets, The setup time for WP Rig adds overhead. For a small business site that needs to ship in a week, Create Block Theme or a pre-built theme with customizations may be more practical.
- Teams unfamiliar with Node.js tooling, WP Rig assumes comfort with npm, Gulp, and command-line workflows. If your team primarily works in the WordPress admin, the learning curve may not be justified.
- Projects that need to stay on the bleeding edge of WordPress, Since WP Rig is community-maintained, it sometimes lags behind the latest WordPress core changes. If you need same-day support for new block editor features, starting from scratch with wp-scripts may be faster.
The Bottom Line
WP Rig was ahead of its time when it launched, and the WordPress ecosystem has finally caught up to the problems it was solving. Block themes gave us a better template layer. Theme.json gave us design tokens. The Styles API gave us editor-to-frontend consistency. But none of these tools replaced the need for a serious front-end build pipeline, and that is where WP Rig continues to shine.
If you are building production-grade block themes and you want optimized CSS delivery, automated image compression, hot reloading, and a structured development workflow out of the box, WP Rig deserves a place in your toolkit. Fork it, adapt it for block themes, and let it handle the build complexity while you focus on design and functionality.
The framework never died, it was just waiting for the rest of WordPress to need it again.