Build Commands

ReactWP provides one project pipeline for themes, plugins, mu-plugins, styles, media, and universal render assets. Use the top-level commands for normal work and the focused commands when debugging one target.

Location

All Node tooling lives in configs/. The project does not rely on a globally installed Webpack or Sass CLI.

The important files are:

• package.json: commands and exact dependency versions
• webpack.shared.config.js: shared bundle factory
• webpack.themes.config.js: configured theme entries
• webpack.plugins.config.js: configured plugin entries
• webpack.mu-plugins.config.js: configured mu-plugin entries
• webpack.render.config.js: universal React renderer entries
• scripts/project-pipeline.mjs: full-project orchestration
• scripts/theme-pipeline.mjs: parallel theme JS/CSS orchestration
• scripts/build-theme-styles.mjs: global SCSS and theme media copying
• scripts/get-core.mjs: WordPress core and optional ACF archive preparation
• scripts/report-bundle-sizes.mjs: production asset validation and budgets
• scripts/generate-static.mjs: WordPress route SSG generator
• scripts/render-server-runtime.mjs: optional production SSR service

Commands

Run commands from configs/.

Command	Purpose
npm run build	one-off development build for every target
npm run watch	watch theme JS/CSS, universal renderer, plugins, and mu-plugins
npm run prod	complete production build and theme report
npm run build:themes	theme JavaScript and CSS, development mode
npm run watch:themes	watch theme JavaScript and CSS
npm run prod:themes	production theme build and report
npm run build:themes:js	development theme JavaScript only
npm run watch:themes:js	watch theme JavaScript only
npm run prod:themes:js	production theme JavaScript only
npm run build:themes:css	development global theme SCSS and media copy only
npm run watch:themes:css	copy theme media once, then watch global theme SCSS
npm run prod:themes:css	production global theme SCSS, media copy, and media optimization
npm run build:plugins	development plugin bundles
npm run watch:plugins	watch plugin bundles
npm run prod:plugins	production plugin bundles
npm run build:mu-plugins	development mu-plugin bundles
npm run watch:mu-plugins	watch mu-plugin bundles
npm run prod:mu-plugins	production mu-plugin bundles
npm run report:themes	report the current built theme entry sizes
npm run build:render	development universal render bundle
npm run watch:render	watch and rebuild the development universal render bundle
npm run prod:render	production universal render bundle
npm run generate	generate static routes from WordPress
npm run serve:ssr	start the optional built SSR service
npm run test:render	build and test renderer, SSG, and SSR service
npm run test:seo-route-language	verify canonical route.lang and legacy SEO language fallback
npm run test:security	run every PHP security/runtime regression plus the get:core security tests
npm run get:core	refresh WordPress core and choose ACF Free, ACF PRO, or no ACF change

Focused PHP regression commands are available when diagnosing one boundary:

Command	Coverage
npm run test:rest-access	exact REST route allowlisting and bypass resistance
npm run test:headless-api-security	exact headless-origin normalization and same-origin request checks
npm run test:route-visibility	public/private WordPress object visibility
npm run test:public-payload	public payload normalization and sanitization
npm run test:preview-token	preview authorization, signatures, and expiry
npm run test:svg-sanitizer	SVG parser and sanitation boundaries
npm run test:render-cache	bounded invalidation history, global invalidation, and lock-contention fail-safe behavior
npm run test:server-security	PHP-to-Node renderer restrictions
npm run test:static-regenerator	removal of stale route entries and fragments from runtime and build manifests
npm run test:firstload	optional first-load scaffold idempotence and ACF references

Use npm run test:security before a release. The focused commands are faster feedback while changing one subsystem, not a substitute for the complete suite.

Build Modes

The pipeline passes mode explicitly through Webpack and Babel.

Development mode:

• emits <theme>.js
• uses readable stable chunk names
• writes source maps
• keeps Webpack's filesystem cache for faster rebuilds
• removes stale production entry and compressed siblings

Production mode:

• emits <theme>.min.js
• uses content-hashed .min.js and .min.css chunks
• disables Webpack filesystem cache to prevent stale asset metadata conflicts
• minifies JavaScript and CSS
• optimizes copied theme images
• emits .br and .gz theme JavaScript/CSS variants
• removes stale development output and old chunks
• runs the theme bundle report
• builds the universal renderer and template render manifests
• runs SSG after the report when RWP_SITE_URL is set

PHP reads the generated manifest, so switching commands does not require a manual enqueue filename edit.

Theme JavaScript

webpack.themes.config.js declares the themes to compile. Each theme entry includes:

• js/App.jsx or js/App.js
• medias/Medias.js

The shared configuration transpiles JavaScript/JSX, resolves assets, splits common dependencies, and turns dynamic imports into lazy chunks.

The initial production entry is grouped into framework, router, motion, vendor, and project assets. The generated assets/js/entrypoints.json preserves the load order for WordPress.

Theme CSS

The global theme entry:

src/themes/<theme>/scss/default.scss

is compiled to:

dist/wp-content/themes/<theme>/assets/css/<theme>.min.css

The filename remains .min.css in every mode for backward compatibility, but development content is expanded and production content is compressed.

SCSS imported from theme JavaScript is handled by Webpack and extracted into CSS chunks. It is not injected into the page through style-loader.

Media Copying

Directories inside src/themes/<theme>/medias/ are copied into the matching theme assets/ directories. This includes images, fonts, video, audio, and other project-managed folders.

In watch mode, that media copy runs once when the style watcher starts. Sass changes continue to rebuild, but later additions, replacements, or removals under medias/ are not watched. Restart the watcher or run another theme build after changing those files.

In production, copied JPG, JPEG, PNG, GIF, WebP, and SVG files are optimized in place when the optimized result is not larger. Sharp handles bitmap formats and SVGO handles vectors. The pipeline does not transcode video/audio or generate alternate image formats.

configs/package-lock.json is source-controlled. Use npm ci in CI and repeatable production environments so the audited dependency graph is installed exactly; use npm install when intentionally changing dependencies and commit the resulting lockfile.

The allowScripts policy in configs/package.json approves only the reviewed, pinned @parcel/watcher install script required by Sass watch mode. Do not replace it with a blanket script allowance; review and pin any future package that requests install-time execution.

Dependency maintenance

Review the complete pinned toolchain from configs/ instead of accepting isolated dependency pull requests without the rest of the graph:

ncu --target latest
npm install
npm audit
npm run build
npm run prod
npm run test:render
npm run test:security

ncu is the npm-check-updates command. Inspect release notes, engine requirements, peer dependencies, license changes, and install scripts before changing package.json. Keep versions exact, regenerate and review package-lock.json, and make sure ncu --target latest reports no remaining update after the install. Running the production pipeline is required when Webpack, Sass, Sharp, SVGO, loaders, routing, or rendering dependencies change because their compatibility is not proven by npm audit alone.

medias/Medias.js remains part of the Webpack entry for assets imported by JavaScript. Avoid importing the same physical source through conflicting asset paths.

Template and Core Copying

Webpack copies each configured target's template/ directory to its WordPress destination. The theme pipeline also copies src/core/ into dist/, which is how the root .htaccess, a locally configured wp-config.php, and other authored core files reach the runnable install. The repository ignores the real wp-config.php; only wp-config-sample.php is intended for source control.

To copy another source directory, add an explicit CopyPlugin pattern to the relevant target config. ReactWP does not copy arbitrary new root folders automatically.

Core Download Flags

npm run get:core supports:

• REACTWP_WORDPRESS_URL: alternate WordPress ZIP URL
• REACTWP_ACF_EDITION: non-interactive free, pro, or none choice
• REACTWP_ACF_LICENSE_KEY: ACF PRO Composer username
• REACTWP_ACF_SITE_URL: complete licensed site URL used as the Composer password
• REACTWP_ACF_VERSION: optional exact Free or PRO version; latest is the default
• REACTWP_ACF_COMPOSER_REPOSITORY: optional compatible PRO Composer repository override
• REACTWP_ACF_URL, REACTWP_ACF_SHA256, and REACTWP_DOWNLOAD_HOSTS: reviewed private PRO archive override
• REACTWP_SKIP_ACF=1: legacy alias for preserving the current ACF installation

In an interactive terminal, the command presents the edition choices. Selecting PRO requests the license key with masked input and then the site URL. CI should use environment variables so the command never waits for input.

Production Details

For manifests, splitting, budgets, compressed files, cache headers, and release verification, continue with Deployment and Performance.

For static generation and the optional render server, continue with Hybrid Rendering.

For every supported environment variable, command-line override, WordPress constant, default limit, and configuration precedence rule, see Configuration Reference.