https://github.com/masonitedoors/react-app-loader
An mu-plugin that provides an API for loading React applications built with create-react-app into the front-end of WordPress.
https://github.com/masonitedoors/react-app-loader
create-react-app wordpress wordpress-plugin
Last synced: 12 months ago
JSON representation
An mu-plugin that provides an API for loading React applications built with create-react-app into the front-end of WordPress.
- Host: GitHub
- URL: https://github.com/masonitedoors/react-app-loader
- Owner: masonitedoors
- License: gpl-2.0
- Created: 2019-11-14T16:26:50.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-04-18T15:34:13.000Z (about 3 years ago)
- Last Synced: 2025-06-08T21:01:52.935Z (about 1 year ago)
- Topics: create-react-app, wordpress, wordpress-plugin
- Language: PHP
- Homepage:
- Size: 55.7 KB
- Stars: 2
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# React App Loader
[](https://packagist.org/packages/masonitedoors/react-app-loader) [](https://travis-ci.org/masonitedoors/react-app-loader)
> An mu-plugin that provides an API for loading React applications built with [create-react-app](https://github.com/facebook/create-react-app) into the front-end of WordPress.
## Requirements
- PHP >= 7.1
- WordPress >= 5.0
- React application built using Create React App >= [3.2](https://github.com/facebook/create-react-app/releases/tag/v3.2.0)
## Setup
### Loader
Add the plugin to your site's [mu-plugins](https://wordpress.org/support/article/must-use-plugins/) directory.
This plugin is also available to install via [composer](https://getcomposer.org/).
```sh
composer require masonitedoors/react-app-loader
```
### React App
While this loader does not require any specific structure to your React application, it does require the React app to be loaded as a WordPress plugin. In order to do this, we will need to add a single PHP file so WordPress can recognize it as a WordPress plugin. Although the PHP file can be named anything, the filename should match the nomenclature of the React app directory name in order to follow [WordPress plugin development best practices](https://developer.wordpress.org/plugins/plugin-basics/best-practices/).
```text
/react-app-name
/public
/src
package.json
package-lock.json
README.md
react-app-name.php
yarn.lock
```
This PHP file (e.g. `react-app-name.php`) [should include header comment](https://developer.wordpress.org/plugins/plugin-basics/header-requirements/) what tells WordPress that a file is a plugin and provides information about the plugin.
Example:
```php
Visiting the Permalinks screen triggers a flush of rewrite rules
[Settings → Permalinks](https://codex.wordpress.org/Settings_Permalinks_Screen#Save_Changes)
Rewrite rules can also be flushed via [WP-CLI](https://developer.wordpress.org/cli/commands/rewrite/flush/).
```sh
wp rewrite flush
```
#### Trailing Slash
Trailing slash has been removed for registerd React app pages. This was done in an effort to create consistency in behavior with create-react-app's node-server structure (the environment that fires up when you run `npm start`).
### Remote React App Support
Support for loading React apps hosted on other websites is available as of version __1.4.0__.
This can be achived by using a URL to the root of the React app For the 3rd argument in the register method.
If your React app's asset-manifest.json is https://example.org/my-react-app/asset-manifest.json, use the first part of the URL (omit asset-manifest.json).
```php
add_action( 'plugins_loaded', function() {
\ReactAppLoader\API::register(
'my-react-app-slug',
'root',
'https://example.org/my-react-app/',
'nopriv'
);
});
```
## Recommendations
### Using Images Within Your React App
It is up the React app to ensure that any images used are using absolute paths. It is recommended to use a digital asset management service such as [Widen](https://www.widen.com/). Any images using relative paths within the React app will be broken when the app is loaded within WordPress.
### Avoiding Conflicting Styles
When the React app is loaded from within WordPress, there is potential for styling conflicts introduced from theme/plugin CSS. It is recommended that you scope your React app's base styles within the React app at a root component using [CSS Modules](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet).
App.js:
```jsx
import styles from "./App.module.scss";
function App() {
return
...;
}
```
App.module.scss:
```scss
// App root styles.
.App {
...
// Our apps base element styles. These will be globally scoped under App.
:global {
h1 {
...
}
p {
...
}
a {
...
}
em {
...
}
}
}
```
Once implemented, our base styles will now be scoped under the root hashed component:
[](https://codesandbox.io/s/kxm1r32j3?hidenavigation=1&module=%2Fsrc%2FApp.module.scss)
## Common Issues
**I am getting a 404 when hitting the page slug I registered.**
Verify that your React app WordPress plugin has been activated. Your site's rewrite rules might not have been flushed or flushed properly. See [Flushing WordPress Rewrite Rules](#flushing-wordpress-rewrite-rules) for instructions.
**I am able to hit the page slug I registered, but my React app is not loading.**
This could be happening from a few things:
1. If your React app is using react router, you may need to specify a basename. This should be the exact same value as the slug registerd with the loader. See [Browser Router](https://github.com/ReactTraining/react-router/blob/master/packages/react-router-dom/docs/api/BrowserRouter.md).
2. The loader relies on the newer asset-manifest.json structure that was introduced in [create-react-app v3.2.0](https://github.com/facebook/create-react-app/releases/tag/v3.2.0). If your React app was built using an eariler version of create-react-app, you will need to update your React app.
3. The asset-manfiest.json could not be found at all within your React app. Most likely your React app was never built or the build failed.
**I am being redirected to my site's homepage when trying to access the page slug I registered.**
This happens when your current WordPress user does not have the same role that was defined when registering with the loader.
## Credit
This plugin is based off the great work done by [humanmade/react-wp-scripts](https://github.com/humanmade/react-wp-scripts).