Skip to main content

Installation

This guide creates a local ReactWP project, downloads WordPress, builds the source tree, and starts the development workflow.

System Requirements​

Before you begin, make sure your environment has:

  • PHP 8.1+
  • Node.js 22.22.0+
  • npm
  • Composer when get:core installs ACF PRO
  • MySQL or MariaDB
  • a local web server that can use dist/ as its document root
  • an ACF PRO license for Site settings, Theme settings, repeaters, and other PRO fields
  • network access while running npm run get:core

The current dependency set has been tested with Node.js 26.5.0.

Node.js is required during development and production builds. It is not required on the production server unless the project enables request-time SSR or runtime static regeneration.

Create the Project​

Clone ReactWP and install its local build dependencies:

git clone https://github.com/studiochampgauche/ReactWP.git my-project
cd my-project/configs
npm install

ReactWP does not require globally installed Webpack or Sass tooling. Its project commands are local npm scripts defined in configs/package.json; there is currently no standalone ReactWP CLI.

The repository tracks configs/package-lock.json. For CI or any repeatable clean installation, use npm ci instead; it installs the exact audited dependency graph without rewriting the lockfile.

Download WordPress​

From configs/, run:

npm run get:core

This downloads and verifies WordPress, then asks which ACF edition to install:

  1. Free downloads the latest standard ACF release from WordPress.org.
  2. PRO asks for the ACF license key with masked input and then the complete licensed site URL. It installs the latest release through the official authenticated Composer repository.
  3. None leaves any existing ACF installation unchanged.

ACF Free supports standard field groups but does not provide the PRO options pages and repeaters used by ReactWP's built-in Site settings and Theme settings. ReactWP hides those unavailable links and keeps the rest of the administration usable.

For non-interactive builds, select the edition explicitly:

$env:REACTWP_ACF_EDITION = 'pro'
$env:REACTWP_ACF_LICENSE_KEY = 'your-license-key'
$env:REACTWP_ACF_SITE_URL = 'https://example.com'
npm run get:core

Use REACTWP_ACF_EDITION=free for ACF Free or REACTWP_ACF_EDITION=none to preserve the current installation. When no edition and no PRO credentials are available in a non-interactive process, Free is the default.

Configure WordPress​

Set the database and environment values in:

src/core/wp-config.php

Then configure your local server so its document root points to:

my-project/dist/

ReactWP uses a source-and-output project model:

configs/   build configuration and Node dependencies
src/       authored WordPress, PHP, React, SCSS, and media source
dist/      generated runnable WordPress installation

Edit files in src/. The build pipeline writes the runnable project to dist/.

Build the Project​

Create the first development build:

npm run build

Open the local domain in a browser. If the database is empty, complete the normal WordPress installation and activate the generated ReactWP theme and required plugins.

ReactWP includes an optional one-time starter scaffold. It is disabled by default and never runs merely because WordPress was installed.

To enable it, temporarily add this to src/core/wp-config.php, rebuild when needed, and visit the WordPress administration as an administrator:

define('RWP_FIRSTLOAD', true);

The scaffold preserves existing content and fills only missing starter values:

  • it keeps the configured front page, reuses a reactwp-3 page, or creates a published ReactWP 3 page
  • it configures that page as the static front page when none is selected
  • it sets /%postname%/ only when the permalink structure is empty
  • it adds French and English rows when language settings are missing or empty, and repairs missing ACF field references
  • it adds the primary location when theme-location settings are missing or empty, and repairs existing rows without replacing them
  • it reuses or creates an empty Primary Navigation menu and assigns it only when primary is unassigned

After a successful run, ReactWP stores rwp_firstload = 1, the default scaffold schema version. Re-enabling the constant can still repair missing required repeater data or ACF references left by an older or interrupted run. Remove RWP_FIRSTLOAD from wp-config.php after verification. The scaffold does not install plugins, activate themes, import demo content, or delete posts, pages, menus, or settings.

Start Development​

Run the complete watcher from configs/:

npm run watch

It watches theme JavaScript, theme SCSS, plugins, mu-plugins, and universal render assets together.

Use these commands for the normal development cycle:

CommandPurpose
npm run watchWatch the complete project
npm run buildCreate a one-off readable development build
npm run prodCreate optimized deployment output and reports

Development emits readable entry files and source maps. Production emits minified entries, content-hashed chunks, compressed assets, and a bundle report. WordPress reads the generated manifest, so entry filenames never need to be switched manually.

Verify the Installation​

After the first page load, confirm that:

  • the default React template renders without an error
  • dist/wp-content/themes/reactwp/assets/js/entrypoints.json exists
  • #reactwp-bootstrap contains valid JSON in the page source
  • /wp-json/reactwp/v1/route?view=/ returns a route response
  • the WordPress admin contains Site settings and Theme settings

If one of these checks fails, start with Troubleshooting.

Next Steps​