Server-side rendering for React-based WordPress plugins and themes.
- PHP 7.0+
- v8js Extension for PHP
react-wp-ssr works best when used with react-wp-scripts to handle the various build processes.
For local development, we recommend the v8js extension for Chassis.
You should already have a React-based WP project ready to adapt, using react-wp-scripts.
Step 1: Add backend library
Add this repository to your project, either with git submodules or Composer. You'll then need to load it into your project:
require_once __DIR__ . '/vendor/react-wp-ssr/namespace.php';
Step 2: Add backend render call
In PHP, call
ReactWPSSR\render() wherever you want to render your app. (Do not include the container yourself.)
For themes, the best practice is to create a minimal
Step 3: Add frontend library
react-wp-ssr to your node modules:
npm install --save react-wp-ssr
Step 4: Replace frontend render call
Developing with react-wp-ssr
By default, react-wp-ssr does not render on the server during development (i.e. with
WP_DEBUG set to true), as it uses your built script; during development, your built script will tend to be behind your live development script, and this will cause hydration errors.
When you do want to test, there are two constants you can use to control react-wp-ssr:
// Define as `true` to render on the server, even during development.define( 'SSR_DEBUG_ENABLE', false );// Define as `true` to only render on the server and skip loading the script.// Useful to check the server is correctly rendering.define( 'SSR_DEBUG_SERVER_ONLY', false );
Detecting the Environment
The callback you pass to
render will receive the current environment as a parameter, allowing you to change what you render when you need to:
(Note that this should be used sparingly, as React's hydration will complain if the HTML does not match what it expects.)
You can also use the
onBackend functions to run callbacks only in a single environment if you need.