WP Rig provides a comprehensive suite of Node.js scripts, accessible via npm run or bun run commands, to streamline theme development workflows. These scripts handle initialization, asset compilation, live development servers, Gutenberg block management, production bundling, and more. They leverage modern tools like esbuild for JavaScript, Lightning CSS for styles, and integrate seamlessly with WP Rig’s component architecture. Running these scripts affects the codebase by processing source files in assets/, generating outputs in build/ or production directories, and sometimes modifying PHP components or configurations. Use them to accelerate iteration, ensure code quality, and prepare optimized themes for deployment.

This reference expands on each script with detailed explanations, all available flags/options (where applicable), usage patterns, and practical examples. Flags are derived from script implementations and config integrations—always run npm run <script> -- --help for inline help. Developers new to WP Rig can copy-paste these examples directly into their terminal for quick wins, building confidence through predictable outcomes like file generations or error-free builds.

Initialization and Setup

npm run rig-init

npm run rig-init

This script initializes a fresh WP Rig theme by installing Node dependencies (silently, without audits or funding prompts), running Composer to fetch PHP packages, and executing the WP Rig CLI init command. It sets up the development environment, ensuring all build tools, linters, and dependencies are ready. Run this after cloning the repo to prepare the codebase for development—no manual npm install or composer install needed. It affects node_modules/, vendor/, and runs post-install hooks like config validation. Ideal for new projects or when switching branches with dependency changes; expect output like “Success: Rig initialized!” on completion.

Options/Flags: None (runs atomically). For verbose output, prefix with npm run rig-init --verbose (npm global flag).

Examples:

# Standard init after git clone
git clone https://github.com/wprig/wprig.git my-theme
cd my-theme
npm run rig-init
# Output: npm WARN deprecated... (suppressed) | composer install... | CLI init complete.
# In a CI/CD pipeline (e.g., GitHub Actions)
- name: Init WP Rig
  run: npm ci && npm run rig-init

bun run rig-init:bun

bun run rig-init:bun

The Bun equivalent of rig-init, using Bun’s package manager for faster installations (often 10x quicker than npm). It performs the same setup but leverages Bun’s speed for dependency resolution and locking. Use this if you’ve configured WP Rig with Bun for a quicker init process, especially in CI/CD pipelines or on resource-constrained machines. It generates a bun.lockb file instead of package-lock.json.

Options/Flags: None. Bun-specific: bun run rig-init:bun --frozen-lockfile for reproducible installs.

Examples:

# Quick Bun init
bun run rig-init:bun
# Output: bun install... (fast) | composer install... | Init success.
# With dry-run for testing (Bun flag)
bun run rig-init:bun --dry-run

npm run setup-child

npm run setup-child

A convenience script that chains rig-init and childify to bootstrap a WP Rig-based child theme. It installs dependencies and then converts the theme into a child theme optimized for inheritance from a parent (e.g., removing conflicting asset enqueues in inc/Assets/). Perfect for developers extending premium or existing themes while retaining WP Rig’s build tools—run it once per project to scaffold a lightweight, customizable child setup. It prompts interactively for parent theme details if not pre-configured.

Options/Flags: Inherits from chained scripts; add --parent-slug=twenty-twenty-four via childify passthrough for non-interactive runs.

Examples:

# Full child setup for extending a parent
npm run setup-child
# Prompts: Enter parent theme slug: astra | Child theme created: astra-child
# Non-interactive with flag
npm run setup-child -- --parent-slug=generatepress

bun run setup-child:bun

bun run setup-child:bun

The Bun variant of setup-child, using rig-init:bun for installation. Choose this for speed gains in child theme prototyping, ensuring compatibility with Bun’s ecosystem while preparing the codebase for parent theme overrides. It updates style.css and PHP components identically to the npm version.

Options/Flags: Same as setup-child; Bun flags like --production skip dev deps.

Examples:

# Fast Bun child setup
bun run setup-child:bun -- --parent-slug=neve
# In a script for multiple children
for parent in astra generatepress; do bun run setup-child:bun -- --parent-slug=$parent; done

Development Servers and Watching

npm run dev

npm run dev

The primary development script that orchestrates a full watch-and-rebuild workflow using BrowserSync. It processes JS/CSS/images, starts a live-reload server, and proxies your local WordPress site for seamless iteration. Source changes in assets/ trigger recompiles, injecting updates into the browser without full reloads. Use this for daily development to maintain a responsive feedback loop, especially when testing theme layouts or PHP templates alongside assets. Configurable via config.json for proxy URL, ports, and HTTPS.

Options/Flags: --no-open (don’t auto-open browser), --port=3001 (custom port). Full list via npm run dev -- --help.

Examples:

# Standard dev server
npm run dev
# Output: BrowserSync proxying http://local.dev | Watching files...
# Custom port, no auto-open
npm run dev -- --port=4000 --no-open
# With HTTPS (config.json: "https": true)
npm run dev

npm run dev:modern

npm run dev:modern

WP Rig’s opt-in modern dev server, a Vite-inspired alternative to BrowserSync for faster hot-reloading (sub-100ms). It uses esbuild for JS and Lightning CSS for styles, proxies your local site (configurable in config.json under dev.browserSync), and auto-injects livereload. Enable via "live": true; it rebuilds on file saves and soft-reloads PHP edits. Ideal for performance-focused devs seeking sub-second feedback—beta feature, but recommended for new projects. Affects no files directly but streams updates.

Examples:

# Start modern server (after config setup)
npm run dev:modern
# Output: Modern dev server on http://localhost:3000 | Proxying local.dev
# With custom dev port
npm run dev:modern -- --port=4000  # Or set devPort in config

npm run dev:modern:debug

npm run dev:modern:debug

A debug mode for the modern dev server, enabling verbose logging, stack traces, and environment variable WPRIG_DEBUG=1. It mirrors dev:modern but adds diagnostics for troubleshooting proxy issues, port conflicts, or build errors (e.g., “Port 3000 in use”). Run this when the server crashes or behaves unexpectedly to inspect logs and verify config settings like proxyURL or SSL paths. Logs include file change events and error stacks.

Options/Flags: --debug (extra traces), WPRIG_DEBUG=1 (env var for toggles).

Examples:

# Debug with env var
WPRIG_DEBUG=1 npm run dev:modern:debug
# Output: [DEBUG] Proxying to local.dev:8888 | [ERROR] SSL cert invalid - check keyPath
# Quick port check
npm run dev:modern:debug -- --port=3001

npm run start

npm run start

An alias for the legacy dev process (pre-modern server), starting the BrowserSync watcher. It builds assets once and watches for changes, suitable for older workflows or when disabling the modern server via "live": false in config. Use as a fallback if modern dev isn’t configured, ensuring continuity during transitions. It proxies and reloads similarly but without esbuild/Lightning CSS speedups.

Options/Flags: Same as dev: --no-open, --port.

Examples:

# Legacy start
npm run start -- --no-open
# Force legacy (config: "live": false)
npm run start

Asset Building and Linting

npm run build

npm run build

Performs a one-time build of all assets (JS, CSS, images) without watching or serving. It compiles sources from assets/src/ into build/, applying optimizations like minification, autoprefixing, and image compression. Essential before commits or testing isolated changes—run it standalone to verify builds or integrate into custom workflows. Clears prior builds for clean outputs.

Options/Flags: --phpcs (run PHP lint post-build), --watch (alias to dev, but rare).

Examples:

# Full one-time build
npm run build
# Output: JS built (2.1s) | CSS compiled (1.2s) | Images optimized
# With PHP lint
npm run build --phpcs

npm run build:js

npm run build:js

Compiles JavaScript/TypeScript from assets/js/src/ using esbuild, outputting to build/ with tree-shaking, bundling, and ES module support. Supports modern syntax; affects the theme by generating enqueued scripts in inc/Assets/. Use for targeted JS rebuilds during debugging or when tweaking polyfills via .browserslistrc. Handles multiple entry points automatically.

Options/Flags: --dev (sourcemaps, no minify), --minify (force prod minify).

Examples:

# Prod JS build
npm run build:js
# Output: index.js -> build/index.min.js (gzipped: 5KB)
# Dev build with maps
npm run build:js --dev

npm run dev:js

npm run dev:js

Development variant of build:js, enabling sourcemaps and unminified output for easier debugging. It processes the same sources but preserves readability, integrating with watch processes. Run manually to refresh JS during live sessions without full rebuilds; outputs to build/ with .map files.

Options/Flags: Same as build:js.

Examples:

# Quick JS refresh in dev
npm run dev:js
# Output: Dev build complete - sourcemaps enabled

npm run lint:js

npm run lint:js

Lints JavaScript/TypeScript files in assets/js/src/ using ESLint with WordPress, standard, and TypeScript configs. It enforces coding standards, catching errors like unused vars, import issues, or React hooks violations before they propagate. Integrate into pre-commit hooks (e.g., Husky); fixes can be auto-applied via --fix or editors like VS Code.

Options/Flags: --fix (auto-fix issues), --quiet (no warnings).

Examples:

# Lint and fix
npm run lint:js -- --fix
# Output: 3 errors fixed in src/app.js
# Strict lint only
npm run lint:js -- --quiet

npm run watch:js

npm run watch:js

Watches JS sources for changes and rebuilds incrementally with esbuild. It’s a lightweight watcher for JS-only iteration, complementing full dev scripts. Use in multi-task setups (e.g., via npm-run-all) for focused frontend work; logs rebuild times for performance tuning.

Options/Flags: --dev (dev mode).

Examples:

# JS-only watch
npm run watch:js --dev
# Output: Watching src/*.js | Rebuild: 45ms

npm run build:css

npm run build:css

Compiles CSS from assets/css/src/ (and block styles) using Lightning CSS, adding prefixes, nesting, and custom media queries. Outputs optimized stylesheets to build/, affecting theme enqueues via wp_enqueue_style. Run for production-like CSS checks or post-design tweaks; supports variables and imports.

Options/Flags: --dev (sourcemaps), --minify=false (no minify).

Examples:

# CSS build
npm run build:css
# Output: style.css -> build/style.min.css (gzipped: 12KB)
# Dev CSS
npm run build:css --dev

npm run dev:css

npm run dev:css

Dev mode for CSS building, generating sourcemaps and verbose output. It mirrors build:css but aids debugging with line mappings to sources. Essential for tracing style issues in browser dev tools during active styling; includes unused CSS warnings.

Options/Flags: Same as build:css.

Examples:

# Debug CSS changes
npm run dev:css -- --minify=false
# Output: Sourcemaps generated for editor.css

npm run lint:css

npm run lint:css

Lints CSS files using a custom script (integrating Stylelint), enforcing best practices like specificity limits, vendor prefixes, or no !important. It scans sources and builds, flagging maintainability issues like duplicate selectors. Use before pushes to uphold code quality in team environments; configurable via .stylelintrc.

Options/Flags: --fix (auto-fix), --format=compact (output style).

Examples:

# Lint CSS
npm run lint:css -- --fix
# Output: Fixed 2 selector issues in src/main.css

npm run watch:css

npm run watch:css

Sets up a Chokidar watcher for CSS sources in src/styles/, rebuilding on saves with Lightning CSS. It’s a standalone watcher for CSS-heavy workflows, decoupling from JS or full dev servers. Pair with tools like Live Sass Compiler for hybrid setups; logs file paths on change.

Options/Flags: --dev.

Examples:

# CSS watch session
npm run watch:css --dev
# Output: Watching src/styles/ | Change detected: rebuild 200ms

npm run build:blocks

npm run build:blocks

Builds all Gutenberg blocks in assets/blocks/, compiling JS/TSX and CSS per block into build/. It handles editor/frontend styles separately, updating block.json asset paths with file: protocol. Run after adding blocks to ensure registration and enqueues work; processes dynamically via glob patterns.

Options/Flags: --watch (continuous), --one (single block via slug).

Examples:

# Build all blocks
npm run build:blocks
# Output: Built 5 blocks: hero (JS 1.2s, CSS 0.8s)
# Single block
npm run build:blocks --one hero

npm run start:blocks

npm run start:blocks

Watches and rebuilds blocks incrementally with --watch flag. It monitors src/index.* and style files, hot-reloading in the editor via script injection. Crucial for block devs iterating on custom controls or renders without restarting the site; supports TS/JSX hot-reload.

Options/Flags: --one=slug (watch single).

Examples:

# Watch all blocks
npm run start:blocks
# Output: Watching blocks/ | Hero edit.js changed - reloaded
# Focused watch
npm run start:blocks --one= testimonial

npm run images

npm run images

Optimizes images in assets/images/src/ using Sharp and Imagemin, compressing (PNG/JPG to 70% quality) and converting to modern formats (e.g., WebP/AVIF). Outputs to build/ with responsive variants if configured; reduces bundle sizes by 50-80%. Run during asset audits to improve performance without manual tools like Photoshop.

Options/Flags: --quality=80 (custom compression), --formats=webp.

Examples:

# Optimize all images
npm run images
# Output: hero.jpg -> webp (45KB -> 12KB)
# WebP only
npm run images --formats=webp --quality=90

Gutenberg Block Management

npm run block:new

npm run block:new

Scaffolds a new static Gutenberg block in assets/blocks/<slug>/ using @wordpress/create-block. Generates block.json, edit/index.js, save.js, and optional styles; auto-updates PHP registration in inc/Blocks/Component.php and Theme.php. Use for theme-scoped blocks—namespace defaults to theme slug. Fails gracefully if directory exists.

Examples: (Note: Use -- for npm passthrough)

# Simple static block
npm run block:new -- hero --title="Hero Block"
# Dynamic TS block with styles
npm run block:new -- testimonial -d --ts --title="Testimonial" --category=widgets --view
# No styles, custom icon
npm run block:new -- cta --no-style --no-editor-style --icon="megaphone"

npm run block:new:dynamic

npm run block:new:dynamic

A shortcut for block:new --dynamic, creating blocks with render.php for PHP-side rendering (e.g., ACF fields or queries). It sets block.json.render = "file:./render.php", enabling dynamic content like recent posts. Includes placeholder PHP boilerplate; auto-includes on registration.

Options/Flags: All from block:new except --dynamic (implied).

Examples:

# Basic dynamic
npm run block:new:dynamic -- recent-posts --title="Recent Posts"
# With keywords and description
npm run block:new:dynamic -- query-loop -d --title="Query Loop" --keywords="posts,archive" --description="Dynamic post grid"

npm run block:list

npm run block:list

Lists all discovered blocks from assets/blocks/*/block.json, showing namespaces, titles, paths, and types (static/dynamic). It scans without building, helping inventory management or debugging registrations. Output in table/JSON for scripting.

Options/Flags: --format=json (or table/csv).

Examples:

# List blocks
npm run block:list
# Output: | wprig/hero | Hero Block | static | assets/blocks/hero/
# JSON for scripts
npm run block:list --format=json

npm run block:remove

npm run block:remove

Safely deletes a block directory after Y/N confirmation, removing from PHP registration in Theme.php and cleaning block.json refs. Specify <namespace>/<slug>; skips if not found. Prevents orphaned code—run with caution in shared repos; backs up to .bak.

Options/Flags: --force (no prompt), --dry-run (simulate).

Examples:

# Remove with confirm
npm run block:remove wprig/old-block
# Force remove
npm run block:remove --force wprig/legacy

npm run block:promote-plugin

npm run block:promote-plugin

Exports a theme block to optional/promoted-blocks/<slug>-block/ as a standalone plugin skeleton. Copies assets, block.json, render.php (if dynamic), and adds plugin headers/PHP wrapper with activation hooks. Great for reusing blocks across sites or submitting to WP.org; preserves namespace.

Options/Flags: <namespace/slug> (required), --zip (create ZIP).

Examples:

# Promote to plugin
npm run block:promote-plugin wprig/hero
# Output: Exported to optional/promoted-blocks/hero-block/
# With ZIP
npm run block:promote-plugin --zip wprig/cta

Production and Utilities

npm run bundle

npm run bundle

The production bundler: sets NODE_ENV=production, builds/optimizes all assets (minify, strip comments), generates a new theme directory in wp-content/themes/<slug>/, and optionally zips it. It strips dev files (node_modules, src/), runs translations (.pot via WP-CLI), and replaces strings per config.json. Core for deployment—creates a minified, performant theme ready for upload or GitHub release.

Options/Flags: --phpcs (lint PHP), --no-zip (skip archive).

Examples:

# Standard bundle
npm run bundle
# Output: Production theme: my-theme v1.0.0 | ZIP created (2.5MB)
# No ZIP, with lint
npm run bundle --phpcs --no-zip

npm run bundle:phpcs

npm run bundle:phpcs

Extends bundle with PHP CodeSniffer checks during production build using phpcs on inc/. It lints for WP standards (e.g., no globals, hook usage) before packaging, halting on errors. Use for quality-gated releases, catching issues like deprecated functions; reports coverage.

Options/Flags: Same as bundle.

Examples:

# Bundle with CS
npm run bundle:phpcs
# Output: PHPCS: 0 errors | Bundle complete

npm run bundle:check-all

npm run bundle:check-all

Alias for bundle:phpcs, performing full checks (asset lint + PHP lint + build) in production mode. It’s a one-stop validation script—run before tagging releases to confirm the entire codebase meets criteria, including JS/CSS standards.

Options/Flags: Same as bundle.

Examples:

# Full check and bundle
npm run bundle:check-all --no-zip
# Output: All checks passed | Theme ready

npm run build:phpcs

npm run build:phpcs

Runs a dev build followed by PHP CodeSniffer on inc/ components using WP ruleset. It enforces standards without bundling, reporting errors/fixable issues. Integrate into CI for ongoing quality assurance; supports --fix via phpcbf.

Options/Flags: --fix (auto-fix with phpcbf).

Examples:

# Lint PHP post-build
npm run build:phpcs -- --fix
# Output: Fixed spacing in inc/Assets/Component.php

npm run childify

npm run childify

Transforms WP Rig into a child theme: prompts for parent slug, adjusts style.css header (Template: parent-slug), removes conflicting enqueues (e.g., parent CSS/JS in inc/Assets/), and preserves build tools. It modifies PHP components like Base_Support/ for inheritance and backs up originals. Use to adapt WP Rig for extending third-party themes efficiently; idempotent for re-runs.

Options/Flags: --parent-slug=<slug> (non-interactive), --dry-run (preview changes).

Examples:

# Interactive childify
npm run childify
# Prompt: Parent slug? understrap | Updated style.css
# Non-interactive
npm run childify -- --parent-slug=blocksy --dry-run

npm run block-based

npm run block-based

Converts the theme to a block-based (FSE) setup by stripping classic supports from inc/Base_Support/Component.php (e.g., pingbacks, feed links, title-tag). Generates theme.json with defaults; backs up to .bak. Essential for modernizing themes to Gutenberg-only workflows; idempotent (no-op on re-run).

Examples:

# Basic conversion
npm run block-based
# Output: Removed classic supports | Backup created
# Full prune, dry-run
npm run block-based -- --prune-html5 --drop-title-tag --dry-run

npm run create-rig-component

npm run create-rig-component

Scaffolds a new PHP component in inc/<PascalCase>/Component.php, implementing Component_Interface and registering in Theme.php via add_action('after_setup_theme'). Includes boilerplate for initialize(); speeds modular development for features like custom post types or widgets. CamelCases slug to dir name.

Examples:

# Basic component
npm run create-rig-component "Custom Post Type"
# With templating and tests
npm run create-rig-component "Related Posts" --templating --tests
# Output: inc/Related_Posts/Component.php | Test: ComponentTest.php | Registered

npm run editor-support

npm run editor-support

Generates or updates editor-specific configurations, like block styles in theme.json or enqueues for Gutenberg. It scans inc/ components and assets/blocks/ to enable full site editing support. Run after structural changes (e.g., new blocks) to refresh editor integrations; outputs diff of changes.

Options/Flags: --force (overwrite existing).

Examples:

# Update editor config
npm run editor-support
# Output: Added block styles for hero | theme.json updated
# Force refresh
npm run editor-support --force

npm run generateCert

npm run generateCert

Creates self-signed SSL certificates for local HTTPS via Node’s crypto module. Outputs key/cert paths for config.local.json (keyPath/certPath under browserSync). Use to secure dev proxies, enabling HTTPS testing for mixed-content debugging or PWA features; valid for 365 days.

Options/Flags: --days=730 (custom validity), --out-dir=certs/.

Examples:

# Generate certs
npm run generateCert
# Output: key.pem, cert.pem in ./certs/ | Update config.local.json
# Custom dir
npm run generateCert --out-dir=ssl/ --days=3650

These scripts support both npm and Bun (prefix with bun run for the latter). For advanced configs or issues, check config.json or run with --help where available. Suggestions? Join the discussion.

WP Rig (as of version 3) comes with some WP CLI scripts to help the theme developer workflow. Below is a list of all of scripts, what they do, and how to use them.

wp rig dev_setup

This script is designed for devs that are getting up and running with a new project to help them quickly scaffold their local dev env with a curated set of WP plugins we feel would be helpful during theme development. It also configures essential WordPress pages and settings for a static front page setup.

These plugins include:

• FakerPress
  • FakerPress is a plugin designed to generate dummy content for WordPress sites. This is useful for theme developers as it helps populate a site with posts, pages, users, and other data to test how themes handle different types of content and layouts. It enables developers to simulate real-world scenarios and catch design or functionality issues before launching the theme.
• Theme Check
  • Theme Check is a plugin that allows developers to test their themes against WordPress coding standards and best practices. It runs automated tests to identify issues such as deprecated functions, improper use of hooks, or missing features. This helps theme developers ensure their themes meet the requirements for inclusion in the WordPress.org repository and follow industry standards.
• Query Monitor
  • Query Monitor is a debugging plugin that provides insights into database queries, hooks, PHP errors, and more. For theme developers, it is particularly helpful in identifying inefficient database queries or problematic code in templates. It aids in optimizing theme performance and troubleshooting issues related to theme development.
• Accessibility Checker
  • Accessibility Checker scans websites for accessibility issues and provides reports based on WCAG guidelines. It enables theme developers to identify and fix design and structural problems, ensuring their themes are inclusive and accessible to all users.
• Auto Description
  • Auto Description automatically generates meta descriptions for posts and pages based on their content, improving SEO. For theme developers, it ensures that themes properly support dynamic meta descriptions and display them correctly in the site’s markup.

This script also creates a “Home” page with welcome content, a “Blog” page for posts, and configures WordPress to use a static front page setup.

This list of plugins is subject to change in the future. If you feel any of these plugins are problematic or feel there are other plugins that should be on this list, please share your thoughts with us.

Menu Management Commands

WP Rig includes a suite of commands for generating, exporting, importing, and listing navigation menus. These are invaluable for developers testing theme navigation components, syncing menus across environments, or rapidly prototyping menu structures without manual admin intervention.

wp rig fake_menu_items

This command generates dummy navigation menu items with hierarchical structure, perfect for populating menus during theme development and testing responsive behaviors, accessibility, or custom walker implementations. It intelligently creates or appends to existing menus, with options for depth, item counts, and naming prefixes. All items use “#” as placeholder links, and deeper levels have fewer items to keep the structure manageable.

Usage: wp rig fake_menu_items [options]

Examples:

# Create a basic menu with default settings
wp rig fake_menu_items
# Create 8 top-level items with 4 subitems each, 3 levels deep
wp rig fake_menu_items --menu="Test Menu" --items=8 --subitems=4 --depth=3
# Create a menu and assign it to the primary location
wp rig fake_menu_items --items=6 --depth=2 --prefix="Nav Item" --assign-location=primary
# Create items in an existing menu
wp rig fake_menu_items --menu="Main Navigation" --items=10 --prefix="Page"

wp rig menu_export

This command exports a specified WordPress navigation menu to JSON format, capturing the full structure including items, hierarchy, metadata, and associations. Developers can use this for backing up complex menu configurations, sharing across team members, or migrating between development/staging/production sites without losing customizations.

Usage: wp rig menu_export <menu_name> [--file=<filename>] [--pretty]

Examples:

# Export menu to stdout
wp rig menu_export "Main Menu"
# Export menu to a file
wp rig menu_export "Main Menu" --file=main-menu.json
# Export menu to a file with formatted JSON
wp rig menu_export "Main Menu" --file=main-menu.json --pretty

wp rig menu_import

The counterpart to menu_export, this command imports a JSON menu file into WordPress, recreating the structure, items, and metadata exactly. It’s essential for restoring menus after database migrations or when handing off theme prototypes. Supports dry-run mode for safe testing and overwrite options to handle conflicts gracefully.

Usage: wp rig menu_import <file> [--overwrite] [--dry-run]

Examples:

# Import menu from file
wp rig menu_import main-menu.json
# Import menu and overwrite any existing menu with the same name
wp rig menu_import main-menu.json --overwrite
# Test import without making changes
wp rig menu_import main-menu.json --dry-run

wp rig menu_list

A quick utility to list all registered navigation menus in your WordPress install, with output formats suitable for scripting or quick reference. Helps developers inventory menus before export/import operations or when debugging theme location assignments.

Usage: wp rig menu_list [--format=<format>]

Examples:

# List all menus in table format
wp rig menu_list
# List all menus in JSON format
wp rig menu_list --format=json

Font Management

wp rig fonts_download

This command downloads Google Fonts declared in your theme’s Fonts Component and saves them locally within the active theme directory. By serving fonts from your own assets instead of the Google Fonts CDN, developers gain better control over performance, privacy (e.g., GDPR compliance), and reliability. It generates optimized .woff2 files in subfolders and a corresponding CSS file with @font-face declarations using local paths.

Usage: wp rig fonts_download [--dir=<dir>]

Examples:

# Download fonts to the default directory
wp rig fonts_download
# Download fonts to a custom directory
wp rig fonts_download --dir=assets/fonts

What it does:

• Reads the Google Fonts families declared in the theme’s Fonts Component
• Downloads the corresponding .woff2 files into subfolders under the destination directory
• Generates a google-fonts.css file with local URLs pointing to the downloaded assets
• Prints the path to the generated CSS on success

These commands require WP-CLI installed and execution from the WordPress root directory, with appropriate permissions for plugin installation and menu management. For full options, run wp help rig <command>. If you have suggestions for additional scripts, open a discussion on GitHub.

In Version 3 we added the ability to manage your theme’s custom settings in a standalone page. This page loads a React app that manages your theme settings for you. Furthermore, there is no need to alter the actual React code to manage the settings and fields (unless you want more specific control over the app). Additionally, this React app auto-saves user input as they interact with the app, so no need to hit an actual Save or Update button. It monitors user interaction and auto-saves all settings 2-3 seconds after a change to any field.

The default React app comes designed to rely on a JSON object that dictates the settings IDs, field types, and more. This means that you DO NOT need to know React to work with this new settings page, you only need to understand the JSON structure. You can find the JSON file in /assets/js/src/admin/settingsFields.json.

{
  "tabs": [
    {
      "id": "tab1",
      "tabControl": {
        "label": "Page 1"
      },
      "tabContent": {
        "fields": [
          {
            "name": "option1",
            "label": "Option 1",
            "type": "text"
          },
          {
            "name": "option2",
            "label": "Option 2",
            "type": "text"
          },
          {
            "name": "option7",
            "label": "Robs Custom Setting",
            "type": "text"
          },
          {
            "name": "option8",
            "label": "Robs Now with Gulp?",
            "type": "text"
          },
          {
            "name": "option5",
            "label": "On/Off",
            "type": "toggle"
          },
          {
            "name": "option9",
            "label": "Live/Die",
            "type": "toggle"
          }
        ]
      }
    },
    {
      "id": "tab2",
      "tabControl": {
        "label": "Page 2"
      },
      "tabContent": {
        "fields": [
          {
            "name": "option3",
            "label": "Option 3",
            "type": "email"
          },
          {
            "name": "option4",
            "label": "Option 4",
            "type": "url"
          },
          {
            "name": "option6",
            "label": "Select one",
            "type": "select",
            "options": [
              {
                "label": "Option 1",
                "value": "option-1"
              },
              {
                "label": "Option 2",
                "value": "option-2"
              }
            ]
          }
        ]
      }
    }
  ]
}

You will notice that the default JSON structure allows you to organize your settings into various tabs for various purposes. Currently, the available field types are limited to:

• Text (string, number, password, email, url, and other value types supported)
• Toggle (enable/disable settings with Boolean values)
• Select dropdown

We anticipate adding support for more field types in later versions.

Reading the JSON structure above is fairly self-explanatory. The most important points here are that the “name” for each field must be unique and is the array index string of the value.

Note: The dev node server must be running (or a build is required after each change) while changes are being made to this JSON file in order for updates to be seen in the settings page, as the JSON file gets imported into the app.

Getting saved values

All values are stored in one array that can be accessed using the standard get_option() function in wordpress and use your theme’s name at the beginning of the option name as so: “{your_custom_theme}_theme_settings”.

Example

// The name of the theme in this example is simply "Example"
$settings = get_option('example_theme_settings');

Customizing the settings page

You can customize the settings page to your liking either using PHP (to add content above or below the settings app) or if you are comfortable with React, you can completely customize the app itself, as the build for the app is built right into the regular WP Rig build process. This means that you can add custom settings components like more specific fields types, input mechanisms, or other content.

If you want to remove this settings page to rely on an alternate means of managing your theme’s settings, you can simply disable or remove the Options component in the /inc directory of the theme. If you only want to disable it, then you can find where the component is instantiated towards the bottom of the Theme.php file in the /inc folder and just remove the line new Options\Component(),

WP Rig has many configuration options. All the configuration is located in the config directory.

Default configuration options are defined in the config/config.default.json file. Default configuration values can be overridden in the config/config.json file. config/themeConfig.js is used by gulp and simply merges the two configuration files, do not edit this file.

It is recommended that you change slug, name, author and PHPNamepace. A full, commented configuration is below. Note that you will need to remove all comments from the actual files as comments are not valid JSON.

{
  "theme": {
    // The machine-friendly slug for the theme
    "slug": "wp-rig",
    // The human-readable name of the theme
    "name": "WP Rig",
    // The author of the theme
    "author": "The WP Rig Contributors",
    // The namespace used in PHP files
    "PHPNamespace": "WP_Rig\\WP_Rig"
  },
  "dev": {
    "browserSync": {
      // Whether to live reload the BrowserSync server when source files are changed
      "live": true,
      // The URL to proxy with BrowserSync. This should be the full URl to your local WordPress installation.The port at the end is optional.
      "proxyURL": "wprig.test:8888",
      // The port to use for the BrowserSync server on localhost.
      "bypassPort": "8181",
      // Whether to serve HTTPS from the BrowserSync server
      "https": false
    },
    "debug": {
      // To debug CSS or not. If true, CSS will not be minified.
      "styles": false,
      // To debug JS or not. If true, JS will not be minified.
      "scripts": false,
      // Whether to test PHP files for WordPress coding standards. Disable this if you already do so in your code editor.
      "phpcs": true
    },
    "styles": {
      // Whether to leave CSS variables unproccsed
      "preserveCSSVars": false
    }
  },
  "export": {
    // Whether to create a .zip file when building the production theme
    "compress": true
  }
}

Below is an example config/config.json with some, but not all, default configuration options overridden. In this example naming conventions are defined, the BrowserSync proxy URL is changed, BrowserSync HTTPS is turned on, and no .zip file is made when the production theme is created.

{
  "theme": {
    "slug": "ataylorme",
    "name": "ataylorme",
    "author": "Andrew Taylor",
    "PHPNamespace": "ataylorme\\theme"
  },
  "dev": {
    "browserSync": {
      "proxyURL": "https://ataylormewordpress.lndo.site/",
      "https": true
    }
  },
  "export": {
    "compress": false
  }
}

In addition to using PHPCS in the codebase, we also include PHPCBF tools that help clean code. This is a handy tool that can not only be used by developers locally before creating PRs for their code, but can also be automated as part of your CI/CD pipeline if you’d like. Composer scripts are included in WP Rig to facilitate this.

While SSH’d into your environment that is running composer and in the path of your development theme, you can run commands like:

composer run run-phpcbf

Check composer.json in the root of WP Rig for a full list of composer scripts that are included

This command will scan all of your theme files and attempt to fix all PHPCS errors that can be automatically fixed. It’s important to note that this process will not fix all PHPCS errors, so this is not a silver bullet, but it can greatly impact issues like tabs vs. spaces or differences in line break formatting like LF vs. CRLF.

npm run editor-support

In theme development, block-based themes or Full Site Editing (FSE) is all of the hype right now. The new editor allows WordPress users the ability to build all of their page templates and template parts entirely out of blocks using Gutenberg. This is a theme-specific feature. So depending on your theme, you either have access to the new editor or you don’t. There are two kinds of WordPress themes that have the new editor feature: block-based themes, and universal themes. In this tutorial, we will show theme authors using WP Rig how to convert their theme from a hybrid theme to a universal theme by enabling the new editor in their theme and retaining all of the classic theme features we know and love like the menus and customizer areas.

Adding the Theme Support

WP Rig already has a component designed specifically for managing our theme supports, called Base_Support. In /inc/Base_Support/Component.php, find the action_essential_theme_support() method. At the bottom of this method, add theme support for wp-block-styles and editor-styles, like so:
add_theme_support( 'wp-block-styles' );
add_theme_support( 'editor-styles' );

Create FSE Folders in Theme Root

Next we need to add the folders that manage our exports for page templates and template parts that are authored in the new editor. In the root folder of our theme, we need to add two directories: templates and parts. In the templates directory, we need to create an index.html, which we can just leave empty for the time being.

FSE Engaged!

At this point, you should be able to refresh the admin area of WordPress and see the new Editor area under the Appearance area in the WordPress admin menu.

Bundle Configuration

The next thing we need to do is ensure that our universal theme gets built by WP Rig when we go to “bundle” our theme (prepare to distribute or otherwise deploy). If we bundle right now, we will not have any of the new folders and the editor feature will not be available in the final bundle of our theme. To remedy this issue, all we need to do is add some considerations to the WP Rig configuration JSON files. If you are using your own config file, you can put this there, however, we recommend just overriding the default config file that comes with WP Rig. To do this, open the config.default.json file located in the /config directory. In here, you will find a part of the JSON file usually located towards the bottom where we define export.filesToCopy. In this part of the object, we provide an array that contains all of the additional files we want to copy during the bundle process. Simply add the new templates and parts directories, along with theme.json (a new WordPress standard for defining many style-specific attributes of our theme) to the array, like so:

"export": {
    "compress": true,
    "generatePotFile": true,
    "filesToCopy": [
      "LICENSE",
      "readme.txt",
      "screenshot.png",
      "assets/css/vendor/**/*.css",
      "assets/js/vendor/**/*.js",
      "inc/EZ_Customizer/themeCustomizeSettings.json",
      "templates",
      "templates/*",
      "parts",
      "parts/*,
      "theme.json"
   ]
  }

That’s it! At this point, the Gulp bundle process will carry over these additional folders and files when we perform our npm run bundle command before distributing or otherwise deploying our theme.

In Version 2.1 we added the ability to manage your theme’s custom settings in a much easier way, using a json file, much like do to configure your theme initially. If the case you want to add some custom settings to your theme in the Customize view of the WordPress admin, you can now just navigate to config/themeCustomizeSettings.json and edit the JSON object. By default, the file looks like this:

{
  "theme_name": "wp-rig",
  "settings_id": "wp-rig_theme",
  "sections": [
    {
      "id": "global",
      "title": "WP Rig Settings",
      "priority": 30
    }
  ],
  "settings": [
    {
      "id": "ga_id",
      "label": "Google Analytics ID",
      "section": "global",
      "refresh": false
    }
  ]
}

You can add as many sections and settings into this object as you like. Each setting must correlate to a section defined in the “sections” array prop. There are more details below about acceptable input for this

The structure of the JSON object attempts to follow the args you see being passed in core WordPress as much as possible, however, some liberties were taken to improve simplicity

Once you have edited the JSON object, you should be able to just save and refresh the customizer in the WordPress admin to see your new settings in there. Retrieving the values of these settings throughout your code is as easy as using the get_theme_mod() function while passing it the ID of your setting.

Array structure details

• theme_name: The name of your theme (without spaces – like an ID)
• settings_id: Unique ID for these settings (for storage in the DB)(I might make this optional in the future)
• sections: Define each new section to be added to the customizer. We lumped in id for simplicity. ‘title’ allows for localization
  • Refer to WP Codex Docs for all args
• settings: Each setting is it’s own array in this array of settings. We tried to combine the args for settings and controls as much as possible to keep this as simple as possible. For the most part, all args from this WP Codex function apply. Also All control args can be passed in, view Codex docs for controls for more details on how those work. We changed ‘transport’ to ‘refresh’ because it makes more sense
  • type: (optional) All base core types are currently supported. Type is optional, if not included, a basic text field is assumed. The following more complex types are also supported:
    • Basic Types include: ‘text’, ‘checkbox’, ‘textarea’, ‘radio’, ‘select’, and ‘dropdown-pages’. Additional input types such as ’email’, ‘url’, ‘number’, ‘hidden’, and ‘date’ are supported implicitly.
    • color – Color Picker
    • date – Data/Time Picker
    • media – Image/Attachment Selection

Gulp 4 uses an updated CLI (Command Line Interface). If the computer you are using already has Gulp installed, there is a good chance you have an older version of the CLI and you will encounter errors when trying to run WP Rig.

Updating the Gulp 4 CLI

To update the Gulp CLI to work with Gulp 4, run the following commands in the command line terminal:

# Uninstall Gulp globally:
npm uninstall gulp -g
# Install the latest version of the Gulp 4 CLI globally:
npm install gulpjs/gulp-cli -g

You may have to run npm install again from the WP Rig directory to ensure Gulp 4 is installed and ready to run.

To take full advantage of the features in WP Rig, your code editor needs support for the following features:

• EditorConfig
• ESLint
• PHP CodeSniffer (phpCS)

VS Code extensions

For VS Code users, here’s a list of recommended code editor extensions.

• EditorConfig
• ESLint
• PHP Debug
• PHP IntelliSense
• PHPCS
• stylelint

To enable PHPCS in VS Code, follow these instructions.

VIM Extensions

• editorconfig: editorconfig/editorconfig-vim.
• ESLint & stylelint: vim-syntastic/syntastic
• Prettier: prettier/vim-prettier
• ALE:  dense-analysis/ale*

*instead of syntastic and vim-prettier, it is possible to configure everything with ALE.

WP Rig uses a gulp to assist in development and to generate and optimize code for production use. This article is an in-depth explanation of the gulp processes in WP Rig. If you want to know how to install WP Rig and get started see README.md.

Background

As of version 2.0 WP Rig is meant to be edited as a development, or source, theme. Once development is complete WP Rig can generate a production version of the code, without the pieces needed for development. This is done to optimize both the development workflow as well as the production theme.

One of the slowest parts of the gulp process in version 1 of WP Rig was string replacement related tasks. With version 2 string replacement does not happen during development, only when the production theme is built.

Version 1 of WP Rig also used a dev subdirectory rather than a source and production structure. This approach is counter-intuitive to how WordPress themes are traditionally developed. Being able to edit any PHP file in WP Rig version 2, without needing to know to only edit the ones in dev, will help lower the barrier to entry for developers new to WP Rig.

Version 2 of WP Rig also took the monolithic gulpfile.babel.js from version 1 and replaced it with more modular files, incorporating modern JavaScript best practices.

Running gulp Tasks

The main gulp tasks, listed below, are run using npm scripts. This ensures that the gulp binary downloaded with npm is used.

• npm run dev
  • Processes all source files and watches files for subsequent changes.
• npm run build
  • Processes all source files once-time and does not watch for changes.
• npm run bundle
  • Creates a production version of the theme, saved to a separate directory in wp-content/theme, that does not include any unnecessary development files, such as asset source files.
• npm run generateCert
  • Generates localhost SSL certificates for use with the BrowerSync proxy server.
• npm run translate
  • Generates a .pot file based on the theme PHP files

gulp tasks not specifically mapped with npm script can still be run using the format npm run dev -- <task_name>, replacing <task_name> with the actual gulp task name. For example, npm run dev -- images will run the image task.

Available gulp tasks suitable to be run independently are:

• images
• php
• scripts
• styles
• editorStyles

Explanations of each gulp task are detailed in the next section of this article.

gulp Tasks and Files

gulpfile.babel.js

gulpfile.babel.js is the main gulp file. Using gulpfile.babel.js instead of gulpfile.js tells gulp to process the file with Babel. This allows modern JavaScript to be used when writing the gulp functions themselves.

The purpose of gulpfile.babel.js is to define all available gulp tasks. This is done by exporting a named function for each task.

The main functions doing work are defined in separate files in the gulp directory and imported at the top of gulpfile.babel.js. Larger functions, using gulp parallel and series to define a specific order for the smaller functions, are then defined. Theme larger functions are then exported so that they become gulp tasks.

All of the smaller imported functions are exported as-is as well to allow them to be run as independent gulp tasks if desired.

Other gulp files

constants.js

constants.js is where constants for use in other gulp files are defined. Mainly this consists of file paths so that they do not need to be defined each time they are used and can easily be changed in one file.

utils.js

utils.js is a collection of utility functions that other gulp functions make use of. If logic was repeated in multiple gulp functions it was moved here to avoid repetition.

browserSync.js

browserSync.js defined BrowserSync related functions. Mainly, a BrowserSync proxy server. There is also a reload function which will refresh the BrowserSync server instance.

generateCert.js

generateCert.js uses create-cert to programmatically generate SSL certificates for localhost. These certificates are required to use HTTPS with the BrowserSync server.

images.js

images.js uses gulp-imagemin to optimized images.

php.js

php.js reads PHP files and, optionally, uses PHP Code Sniffer to check them against WordPress Coding Standards.

If gulp is being run in production mode then the PHP files have the WP Rig name replaced and are saved to the production directory, in addition to the steps above.

scripts.js

scripts.js reads JavaScript source files, uses ESLint to check them against WordPress Coding Standards, transpiles the files with Babel, and saves a minified version to the assets directory.

If gulp is being run in production mode then the optimized JavaScript files have the WP Rig name replaced and are saved to the production directory, in addition to the steps above.

styles.js

styles.js reads CSS source files, uses PHP Code Sniffer to check them against WordPress Coding Standards, transpiles the files with PostCSS, and saves a minified version to the assets directory.

If gulp is being run in production mode then the optimized CSS files have the WP Rig name replaced and are saved to the production directory, in addition to the steps above.

editorStyles.js

editorStyles.js runs the same process as styles.js, except it used editor-styles.css, which is enqueued for the block editor in the WordPress admin. Styles placed here are ones necessary for the block editor but not the front-end of the site.

translate.js

translate.js reads the theme PHP files and uses gulp-wp-pot to generate a .pot file.

watch.js

watch.js watches PHP, JS, CSS, image and configuration files. When they are changed the proper tasks are re-run and the BrowserSync server reloads.

prodPrep.js

prodPrep.js is run if gulp is in production mode before other file processing tasks are run. The production directory is created and necessary files that are not otherwise processed with gulp, such as readme.txt, are copied to the production theme.

prodFinish.js

prodFinish.js is run if gulp is in production mode after other file processing tasks are run and a .zip file of the production theme is created.