WP Rig v3.2.0 Is Here — Build, Verify, and Ship With Confidence

WP Rig v3.2.0 has officially landed, and this release marks more than just another version bump. It represents a clear shift in focus: making WordPress themes easier to confidently ship.

Not just for agencies.
Not just for private client work.

This release begins a broader 2026 commitment to ensuring that themes built with WP Rig are better prepared for submission to the official WordPress theme repository, and better aligned with the expectations of the WordPress Theme Review Team.

WP Rig v3.2.0 is about helping theme authors catch issues earlier, reduce friction during review, and ship themes with clarity and confidence.

From Development to Delivery — With Fewer Surprises

Shipping a WordPress theme is about more than writing clean code. It is about answering difficult questions before a reviewer, client, or user ever sees your work:

• Does this theme behave correctly across real user flows?
• Are performance, accessibility, and SEO measurable and verifiable?
• Are there structural or PHP issues that could trigger review feedback?
• Can problems be identified proactively, rather than reactively?

WP Rig v3.2.0 is designed to help you answer those questions while you build, not after rejection or review feedback.

Confidence Through Verification

End-to-End Testing with Playwright

Manual testing is unreliable, inconsistent, and easy to skip under deadline pressure. WP Rig now includes Playwright-based End-to-End (E2E) testing to help theme authors validate behavior in real-world scenarios.

These tests can cover:

• Navigation and page interactions
• Accessibility and interaction flows
• Smoke tests that ensure critical paths work as expected

For theme authors preparing for submission, this provides a tangible way to confirm that key behaviors function consistently — before a reviewer ever touches the theme.

Lighthouse CI — Measure What Reviewers Care About

Performance, accessibility, SEO, and best practices increasingly matter in theme review — and they matter even more to end users.

WP Rig v3.2.0 introduces Lighthouse CI configurations that allow you to:

• Assess performance and accessibility during development
• Identify regressions early
• Make measurable improvements with confidence

Rather than guessing how a theme might perform under scrutiny, you can now evaluate those metrics directly in your workflow.

PHPStan — Fewer Issues, Cleaner Submissions

Static analysis is one of the most effective ways to reduce subtle bugs and review feedback.

By integrating PHPStan, WP Rig helps theme authors:

• Identify PHP issues before submission
• Improve code correctness and maintainability
• Reduce avoidable back-and-forth during theme review

This benefits both authors and reviewers by catching issues at the source.

Modern Features, Without Compromising Review Compatibility

Theme-Level Blocks — Now Explicitly Opt-In

Theme-level blocks remain an important part of modern WordPress development, but compatibility with the WordPress.org theme checker is non-negotiable.

In v3.2.0, theme-level blocks are now explicitly opt-in via a dedicated script, giving authors full control over when and how they are used.

This ensures:

• Maximum compatibility for repository submissions
• Clear intent and configuration
• No accidental review blockers

Modern tooling should empower authors — not surprise them.

A More Reliable Mobile Experience

Mobile usability is critical for both reviewers and users. The default mobile navigation has been refined to eliminate transition issues and ensure smoother, more predictable behavior across devices.

Refinements That Add Up

Beyond new tooling, WP Rig v3.2.0 includes a broad set of stability and quality improvements:

• Streamlined and optimized dependencies
• More resilient CLI behavior
• Bundled test data for immediate E2E test execution

These refinements reduce friction, remove guesswork, and make the framework feel more dependable from day one.

A Commitment to the Entire WordPress Ecosystem

WP Rig is built for:

• Agencies delivering high-quality client work
• Independent theme authors
• Open-source contributors
• Anyone serious about modern WordPress theme development

This release begins a deliberate, long-term effort to lower the probability of theme rejection, while also making the Theme Review Team’s job easier by empowering authors to self-assess before submission.

The goal is simple:
Better-prepared themes.
Fewer surprises.
A healthier WordPress theme ecosystem.

Looking Ahead

WP Rig v3.2.0 lays the foundation for what comes next. As we move toward 2026, expect continued focus on:

• Review readiness
• Developer confidence
• Measurable quality
• Modern tooling aligned with WordPress core expectations

WP Rig is not just a starter framework. It is becoming a professional-grade, review-aware theme development toolkit designed to support the full lifecycle of a WordPress theme — from first commit to final approval.

WP Rig 3.1 is here and it is jam packed with improvements and new features for theme developers. Lets go through what’s new. Buckle up, because there is a lot here.

Performance

In v3.0, we dramatically overhauled the JS and CSS compile system in WP Rig to improve performance and move away from older less performant processes. While this brought huge performance gains to WP Rig, this was really just phase 1 of 2 phases. In 3.1, we have finished phase 2 of this process, removing our dependency on Gulp altogether. While Gulp was great to us in the past, the package has become bloated over the years, support has been questionable, and efforts to modernize it have been less than ideal by today’s standards. So, instead of attempting to find a new task manager, we decided to write our own bespoke internal node scripts for performing many of the main WP Rig task processes. As a result, WP Rig 3.1 is even faster than 3.0, boosting build speeds by approx 2x of 3.0.

We didn’t stop there either. While BrowserSync is still a pretty cool technology, it is a bit slow and dated by modern standards. In an effort to keep up with the times, we decided that we needed something closer to HMR (hot module reloading). While true HMR is not technically possible in the scope of PHP, there are some interesting concepts that have been brought forward over the last decade that get PHP/WordPress sytems much closer to this kind of developer experience. So, with that said, we now have a more modern watch process built into WP Rig that makes realtime updates to your theme faster than ever!

Believe it or not, this puts WP Rig’s build, watch, and bundle processes up to par with modern systems like Vite. What a time to be alive!

Modernizations

The goal of WP Rig is to remain a progressive and cutting edge toolkit for WordPress theme developers. As the web continues to evolve, so must WP Rig.

Image processing

Previously, all image processing in WP Rig was done by imagemin. Well, there’s a new kid on the block and it’s pretty good. Now, WP Rig leverages Sharp for all image processing. This means better and faster image processing. How images are processed remains similar to before, just faster, better, and lighter. Just a reminder, WP Rig does now convert to webp for you and the image processing task was moved out of the dev/watch server to speed up Rig, so images are now processed using the dedicated command, or by the build or bundle processes.

Bun Support

WP Rig now supports (and encourages) the usage of Bun. While we kept npm support (for now) for those who have not jumped on the Bun train yet, we do highly recommend installing Bun and leveraging this new and extremely fast and powerful all-in-one JavaScript, TypeScript & JSX toolkit. You will be amazed by the blazing fast performance. Also, as we move forward, it is highly likely that some future WP Rig features will require Bun to leverage them in an a continued effort to keep our dependency tree as small as possible.

Command Prompts

In an effort to improve the DX of WP Rig, we have begun leveraging command prompts to make WP Rig more intuitive. This means less having to remember specific steps and less manual adjustments to config files and such. The rig-init command now prompts for basic config details after installing all Node and Composer packages to help new users set up their BrowserSync/HMR config and better guide users. These are also used in our new component generator and childify conversion.

New scripts, commands, and generators

While building the latest version of this website’s theme, some obvious room for improvement was discovered. We even made a blog post highlighting some of our learnings and we were committed to improving. This means less common manual file manipulation, and more automation.

Learn more about how our cli scripts

Component generation

Creating new PHP components seemed way too necessary/common in more theme builds and the process was just unnecessarily manual. With that in mind, we have added a new cli command to automatically scaffold new components for you. This process not only creates the necessary folder and file for your new component in the /inc folder, but it also adds this component to the Theme.php class for you. This means you just run the command and dive right into your new Component.php file already set up with a standard structure and method declarations. Now creating new components is faster and easier than ever.

Child Themes

Historically, WP Rig was only able to be used as a parent theme. If you wanted to build a child theme for another theme and wanted a build process to compile your child theme’s custom JavaScript or CSS, you had to manually set up/configure some other build/bundling system from scratch in your child theme (Webpack, Vite, etc.). So we thought, “Why can’t WP Rig be used for child themes anyway?”. After much thought, we realized there was really no good answer to this question. So, just like you can convert WP rig to a universal or block based theme, you can now also convert it to a child theme. Just run a single cli command and Rig will guide ask for some input before modifying the WP Rig codebase to be used as a child theme. This basically means it will remove a fair number of features from WP Rig that only make sense for parent themes and also add a dependency on your parent theme of choice. Presto! Now you have a child theme with multiple build processes, allowing WordPress developers relying on any theme (premium or not) to modify that theme’s functionality progressively for any client project.

Fonts

Relying on Google fonts like most web developers do? We get it. It’s easy, there a lot of good ones to choose from, and best of all – no licensing worries. The only problem with Google fonts is having to rely on their CDN. This is not the best practice. It is much better for reliability and performance to host your font files on your website’s server. So why not bundle these fonts into your theme? WP Rig now has a new command that will use the built-in Fonts component to scan for any registered Google fonts in the theme and download the font files directly into the /assets/fonts directory while also writing some boilerplate css to register the fonts for usage with relative pathing to these font files. That’s it. Now you can start using these fonts in your theme without having to make requests to the Google CDN. Better performance. Better reliability. Better security. Better theme.

Theme-level Block development

Trigger warning – we believe that in very specific scenarios, it makes sense to build custom Gutenberg blocks into your theme instead of a plugin. Now, before you raise any pitch forks or just stop reading to flame WP Rig, please hear us out.

We get it, blocks should be a plugin-level concern – we completely agree. In most cases, we recommend building your custom blocks using the @wordpress/create-block package which is designed to build your blocks as a plugin. It’s great and we would never recommend always building any block into your theme as it limits your block’s modularity, portability, and the ability to deactivate it separately from your theme.

With that said, now that blocks can be used across your entire site, not just the page/post content, the lines are blurring. Navigation, search functionality, accessibility, and other concerns often make sense to build into your theme, especially when you consider that custom menu walkers are also often part of the theme as well. Also, many bespoke site projects can be rather involved and your custom theme can easily become the main driving force of the site experience.

Adding functionality to your theme, while technically not proper because functionality should always be the responsibility of plugins, in some cases does make sense. Furthermore, we believe the plugin manager in WordPress fails to address the issues and separation of concerns that prevent admins from effectively managing large numbers of plugins. This problem becomes exacerbated by the entire concept of block plugins. If a site is always going to be reliant on it’s bespoke theme, and this theme is often going to manage the styles of custom blocks, then what really is the problem (as long as you are not planning on distributing your blocks or using them across multiple projects)?

So, with all of this mind, we thought it would be ideal to provide theme developers with the option to build some of their custom blocks into their theme using the existing WP Rig build system. Our new block development system will create/register blocks, list blocks, remove blocks, build blocks, and even move blocks out to a plugin if you realize later you want to use one of these blocks in other projects or share them. This new system is based on the create-block package, so you would develop blocks in WP Rig the same way you would for create-block.

Learn more about how our new block system works

Block Based Themes

While previously we added a command to add Site Editor support to your theme by converting it to a universal theme, it still required some manual effort to convert it to a truly block-based theme. Now we have added a command to convert your universal theme to truly block-based theme with a single command. So, to make a truly block-based theme, WP Rig theme devs will now add editor support, then convert to block based. This essentially removes support for the Customizer, menu manager, and any other features that become obsolete with the concept of full site editing. Added editor support to your theme (universal or block-based) now also generates a starter theme.json file for you.

Other enhancements

• New wp cli commands for mocking menus and importing/exporting menus between sites/environments
• A number of long lasting bugs have been addressed
• All new default header, primary nav and mobile navigation styling and walker for a better starting point
• More organized css
• Better nav accessibility
• Improvements to eslint system, TS compiling, styles and js minification
• Less dependencies
• and more

See the CHANGELOG.md file for more details.

Conclusion

I (Rob Ruiz) hope everyone finds these new features and enhancements valuable. I remain committed to this open source project. I will continue to build enhancements to this extremely powerful and beneficial theme development tool as I continue to grow my skills building custom Node/Bun tooling and focusing on the DX of WP theme developers. I have many more ideas for enhancements to this tool. I will always welcome open-source contributions from the community as they align with the needs of the WP Rig user base.

Many thanks to those that continue to use WP Rig. Please share this exciting news with other WP dev you know. Please lets us know what you think in the discussion boards on Github.

We wanted to get WP Rig V3 released by Jan 1, and we did. However, as usual with software, there was still some unfinished business and some optimizations we noticed after release. Below is a summary.

Support for Dark Mode

The base starter theme now supports dark mode for users using the prefers-color-scheme: dark browser feature. So depending on how you have your OS (or browser) configured, you will see the starter theme either dark or light. You can find the majority of these concerns handled in the _custom-properties.css file towards the bottom of the file. If you do not wish to support these @media browser feature (not recommended), you can simply remove that whole section.

PHPUnit

PHPUnit has been updated and upgraded to work with PHP8+. Some of the base unit tests have also been updated accordingly to ensure all tests pass on a fresh WP Rig install.

PHP Code Quality

Rector PHP and PHP CS Fixer have both been added to the stack. Rector helps you modernize old/outdated/unnecessary code and PHP CS Fixer helps you bulk address certain issues the PHPCBF (PHP Code Beautifier and Fixer) does not (like Yoda conditionals) which may be pointed out by PHPCS (PHP Code Sniffer) using WPCS (WordPress Coding Standards). Because this new stack is a bit more complex, we added a new composer script for convenience:

composer run fix

This new composer script runs rector, then runs PHP CS Fixer, then runs PHPCBF all in that sequence.

Rector PHP -> PHP CS Fixer -> PHPCBF

We recommend always running phpcs (composer run run-phpcs) after this to ensure everything has been addressed as these tools do not automatically fix every single possible issue. It’s also a obviously a good idea to thoroughly test after running such automated code changes.

The combination of all of these tools should help developers to learn to write more modern, maintainable and cleaner PHP. A lot can be learned from reviewing the code that was changed from these, so be sure to dive into your git changes after running these before committing them.

Nav Accessibility

The nav was already very accessible by modern standards. However, we noticed issues in a scenario where you want to create a parent nav item that has a sub-menu where the parent nav item does not link anywhere (its only for the user to however over and control the open/close of the sub menu). In this scenario usually devs will make the parent nav item link either blank (an empty string / “”) or “#”. In this scenario, it is bad for accessibility to have the menu item contain an anchor tag (<a>).

We have actually secretly enhanced the default accessibility for this scenario over the past few versions (even before v3). We will make a new video outlining the specific nuances around this in the future, but just know that we have made it much more convenient to control the main navigation for users TABbing through the nav or using other assisted tech to navigate.

This was discovered using the Accessibility Checker plugin, which is one of our curated plugins that get installed when you run the new WP CLI command we added: wp rig dev_setup.

So, we added a filter that changes this anchor tag to a button element (<button>) as this is the recommended approach. We also added very specific styling to ensure that these buttons match the anchor tags in the main nav so there is no visible difference between these elements in the main nav to the user. This is important to note as this could have consequences in scenarios where devs do use CTA (or other) buttons in their main nav for whatever reason. In this scenario, you would want to override those CSS rules with more specific CSS selectors.

Other

A variety of other minor bug tweaks were made, all of which can be found in the commit history in the Github repo. We won’t list them all here, but one worth mentioning is that the command line output when running some npm scripts:

• npm run rig-init has been cleaned up and slimmed down a bit to be less busy (this can be undone by editing the script in composer.json if you prefer a more verbose output).
• npm run dev, build, and bundle have also been cleaned up a bit.

WP Rig V3 is now live. Check out the video above for a walkthrough, or you can refer to our previous blog post about the beta for more details about this update. Stay tuned to our YouTube channel as we add more build guides and walkthroughs on this new version.

Changes

Thanks to the WordPress Coding Standards folks updating WPCS to V3, we have upgraded that dependency in WP Rig so now PHPCS gives you more updated coding standards straight from the WordPress team.

We noticed some significant room for improvement in the default mobile menu experience, so we decided to upgrade that. The default mobile menu now properly supports accordion style expand/collapse functionality for sub menus.

Furthermore, we have taken some significant time and consideration into make WP Rig as easy as possible to convert to a Universal theme (unlocking block-based features like full site editing). The revamped mobile menu now also works with the Gutenberg Navigation block. So menus built with the navigation block offer a very similar experience to the standard main navigation, but be sure to double check all settings at the block level for expected layout and functionality. Depending on how you layout your header, you will need to tweak the CSS for the navigation to ensure a good UX.

We have had a video on our YouTube channel showing you how to convert WP Rig to a universal theme, however, we wanted to take it one step further. We have now included a node script that can be run via the command line to execute all of the steps outlined in the video with one command:

        npm run editor-support

Please note that once you have run this script, you will need to create/edit your index page template in the Site Editor to see your website. Currently, the script inserts a completely blank index file, so be aware of that. The index page template overrides the default index.php. All other page templates should work accordingly. We recommend building your header and footer as template parts (synced block patterns), then just using the Content block in between.

Changelog – 2.3.1

• Updated WPCS to V3. Props @robruiz
• Improvements to mobile navigation, primarily collapsible sub-menus, including consideration for Gutenberg navigation block. Props @robruiz
• Improvements to header layout. Props @robruiz
• Added FSE Conversion NPM script. Props @robruiz
• Updated all dependencies. Props @robruiz
• Added onload attribute to preload styles. Props @robruiz
• Updated navigation CSS to prevent blocking of content when mobile menu is toggled off and to have smooth transition from toggle-on toggled-off states. Props @Spleeding1

Monthly Contributor meetings are no longer being help, however, our Slack workspace is still up and running and you are welcome to jump in there and ping anyone.

Changes

We have update a couple of the NPM dependencies for WP Rig as well as made some effort into slightly improving accessibility. Also put in a fix that caused php to throw an error that it was looking for a custom.js file that wasn’t there, if you have been working from the 2.2.0 release I suggest you either update or remove the code from Inc/Scripts/Component.php

        'wp-rig-custom' => array(
            'file'    => 'custom.min.js',
            'loading' => 'defer',
            'global'  => false,
        ),

Changelog – 2.2.1

• Extended config file to add the ability to modify author name, author url, theme description and version for production. Props @dthenley
• Bumps ajv from 6.10.2 to 6.12.3.
• Bumps handlebars from 4.7.6 to 4.7.7.
• Change Sidebar screen reader text. see #761
• Update blocks css to use grid css
• Added ‘deps’ to css files array Props @Spleeding1
• Removed call for custom.min.js from the Scripts/Component.php file. Was throwing an error before.

We are looking to hold meetings every month on the first Sunday of the month. Our current time is at 11 am central, but dates and time can change if more people want to attend but it doesn’t fit with their schedule. On that note we are looking for more maintainers so if you are looking to help us grow this project please reach out to us on Github or join our slack. We are planning on putting out the agenda before the next meeting so that those that would like to participate can.