Create React App for Wordpress

A wrapper for create-react-app's react-scripts to allow seamless usage of scripts and styles served from webpack-dev-server while developing a theme or plugin.

Installation & Usage

Step-by-step instructions in documentation

But the tl;dr: Run npx create-react-app app-name --scripts-version @prcdigital/react-wp-scripts to generate a new create-react-app project configured to use these custom scripts.

• Replace app-name with the name of the app, as you want it to appear in the name index of package.json.

You may now use the react-scripts commands as normal while you develop.

Using in WordPress

There are two ways to use this in WordPress:

1. Inside a plugin or theme, you can enqueue your React application by calling this on the wp_enqueue_scripts hook.

$react_support = new \PRC_Core\React();
$react_support->enqueue_assets( 
    get_stylesheet_directory() . '/states-db', // Location, in this example this would be (because its the hispanic theme) /wp-content/themes/prc_hispanic/states-db
    array(), // Pass in an array of options to override in the core function. Optiosn are `scripts` and `styles`. `scripts` will let you declare additional script dependencies, like highcharts.
    false, // "private as base", should always be set to false, true is used by the js_interactive shortcode in local mode.
    $localization // Any information you want to pass through to the script, this is wp script localization so you can include server level information here.
);

2. Inside an interactive. While in local dev you can use a variation of the [js_interactive] shortcode to render your React app.

[js_interactive path="religion/2019/{my-interactive}" id="{my-interactive}" react="true" local="true"]

How It Works

This project solves two issues that prevent seamless usage of Webpack projects in WordPress themes and plugins:

1. WordPress doesn't necessarily know where to look for the output bundles.
2. WordPress cannot access the development server due to cross-origin restrictions.

When you run npm run build in a create-react-app project, react-scripts uses the webpack-manifest-plugin to output an assets-manifest.json file containing the paths of all generated assets. Since files are generated with content hashes in their filename, this file can be ingested from PHP to ensure we are enqueueing the right scripts or styles for our application.

Running npm start, on the other hand, doesn't output a thing: this is because webpack-dev-server compiles files in-memory and does not write anything to disk, but also because the development webpack configuration does not contain that webpack-manifest-plugin (as the output files have no hash). If the dev server used a static host and port we could hard-code the URIs for those development bundles into our WordPress themes and plugins, but react-scripts tries to pick an unused port for your server so the port may change.

react-wp-scripts wraps the default react-scripts "start" command with code that tweaks the development Webpack and webpack-dev-server configuration objects, injecting cross-origin headers, a webpack-manifest-plugin plugin configured to output from within webpack-dev-server, and other optimizations to allow WordPress and the Webpack build to properly communicate. All successful builds will now create an assets-manifest.json file, either at the project root (when the development server is running) or in the build/ directory (as part of a static build).

Finally, the PHP in loader.php uses the location of the generated assets-manifest.json file to enqueue scripts either from the development server or from the static build/ directory.

Troubleshooting

Server will not start

If the development server will not start or WordPress is showing script errors, try deleting the assets-manifest.json in the project root then re-start the development server.

Scripts do not load

If the development server is not running, the root assets-manifest.json is not present, and scripts still will not load, re-run npm run build to re-generate any build assets that may be missing.