WP Rig Node Scripts

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.

Config Option (in config.json)	Description	Default
`devPort`	Proxy server port	3000
`proxyURL`	Local WP site URL (e.g., “local.dev:8888”)	Required
`https`	Enable HTTPS proxy	false
`keyPath / certPath`	SSL key/cert paths (if https: true)	None

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.

Flag	Description	Example
`<slug>`	Block slug (required)	`hero`
`--title <string>`	Human-readable title	`--title="Hero Banner"`
`-d, --dynamic`	Add render.php for dynamic	`-d`
`--ts`	Use TypeScript (.tsx)	`--ts`
`--category <string>`	Block category	`--category=layout`
`--icon <icon>`	Dashicon or SVG	`--icon=admin-site`
`--description <string>`	Block description	`--description="Full-width hero"`
`--keywords <list>`	Search keywords	`--keywords="banner,header"`
`--no-style`	Skip style.css	`--no-style`
`--no-editor-style`	Skip editor.css	`--no-editor-style`
`--view`	Add view.js for frontend	`--view`

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).

Flag	Description
`--dry-run`	Preview changes without writing
`--prune-html5`	Remove HTML5 theme support
`--drop-title-tag`	Remove title-tag action

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.

Flag	Description
`"Component Name"`	Human name (required, space-separated)
`--templating`	Add Templating_Component_Interface + template_tags()
`--tests`	Create PHPUnit test skeleton in tests/phpunit

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.