React-WordPress-Plugin is a WordPress Plugin boilerplate with React on both the admin page and React component rendering on the public page alongside a fully functionally WordPress plugin.
This boilerplate plugin provides certain out-of-the-box features for both development and production:
- 🎉 WordPress plugin boilerplate with
- 🔄 already built-in WordPress hooks (eg. activation and deactivation hooks)
- 🔀 WordPress REST-API endpoint which is already used by the React App
- 📝 plugin options handling with WordPress's Options API (eg. store data in the WordPress database)
- 📃 plugin settings page in wp-admin
- 💥 Sample React-App with example components on the plugin settings-page
- 🌎 i18n support for both React and WordPress, with sample translation *.pot template file
- 🚀 Webpack, react-intl, ESLint, Stylelint and Prettier and other awesome technologies
- Install Node 8.11.1 or greater
- Install Yarn (min. 1.3.2, or npm if you prefer)
- Install Docker
- Install the required modules with
yarn(ornpm install), - start the docker containers with
cd docker && docker-compose up - and finally watch for changes or build the client bundle with
yarn watchoryarn build. - Now open http://localhost:8000, set up WordPress and activate the plugin.
- Finally you can then see the admin page on http://localhost:8000/wp-admin/admin.php?page=plugin-name
To improve the coding experience and efficiency there are helpful scripts available, see package.json for more details.
Additional Notes:
- Docker has to run in order to develop!
- A docker compose file is provided for local development and testing, see docker/README.
- Currently you have to rename
PLUGINNAMEandplugin-namein thesrcfolder to match it with your plugin name. We will add a script for this later on. - You also have to rename all files including
plugin-name(eg. plugin-name.php)
To enable logging in your browser, you have to enter debug mode by running
localStorage.setItem('debug', '*') in your browser's console.
- changes are not visible or plugin is deactivated: just re-start the docker
image and the
yarn watchscript
Generally we have put both React and WordPress into their own subfolder for better maintainability.
/src/react << contains React related code (eg. components)
/src/static << contains static files like images for both React and/or WordPress
/src/wordpress << contains WordPress plugin related code (eg. hooks, actions)
The current boilerplate setup of WordPress is more "sophisticated". This is the reason why we will talk more about it's folder structure.
admin/ << contains code relevant in wp-admin (eg. settings-page)
includes/ << contains i18n, activator and deactivator, generally speaking helpers and plugin wide classes/features
languages/ << i18n translation files
public/ << contains code relevant for the public site of the WordPress instance
static/ << images and other static assets
plugin-name.php << initialises the Plugin and defines Constants
README.txt << describe the plugin, certain features, FAQ and other details
uninstall.php << will be triggered when the plugin will be uninstalled
To interact with the WordPress database React needs to interact with a WordPress REST API. We have already included an example controller class in this boilerplate. We followed the guideline and examples in the WordPress developer documentation. Please take a look at it to familiarise yourself with the topic. You will need to create new endpoints or enhance existing ones to enable React to talk with WordPress and update data.
The boilerplate also includes the creation and setup of a wp-admin menu page. The admin class (see admin/class-admin.php) takes care of adding a menu page and rendering a DOM node for the React app by including views/admin-index.php. From there you can develop the React app in react/admin.js and follow React best practices.
One can easily start translating the WordPress plugin (php-codebase) by first reading the WordPress developer documentation and the i18n for WordPress Developers before following the documentation here: https://wordpress.stackexchange.com/a/258562.
Eventually you will run a command similar to this one to create a pot file:
cd wpdev/tools/i18n
php makepot.php wp-plugin ../../../react-wordpress-plugin/src/wordpress/ plugin-name.pot
From there you can start translating with our preferred editor PoEdit (availble for both Mac and Windows) for instance.
To enable translations in React we use react-intl.
Simply use the following components and methods from react-intl: defineMessages(), <FormattedMessage>, and <FormattedHTMLMessage> in your components. Check out the example in the App component to get started.
Once you have added some translation strings, you can generate the necessary files
to start translating. To create the translation files run either yarn watch or
yarn client. babel-plugin-react-intl
will then create the *.json files (by extracting the default message descriptors)
for each language and our i18n webpack plugin will do
the rest (eg. copy it into dist/static/languages).
All you have to do now is translating the generated *.json files (see
/dist/static/languages/*.json) and putting them back into the static folder
before releasing your plugin.
Attention: babel-plugin-react-intl will overwrite the translation files in
dist/static/languages everytime it runs. This should be improved in the future,
as react-intl-translations-manager
is capable of doing this!
To generate only one default language (currently en) file called en.json run
yarn i18n:generate-default-language after you built the app with yarn build.
Because yarn build uses the custom made webpack plugin to create multiple
translation files for multiple languages (see webpack/common.config.js).
With the command above you can overwrite it.
If you need - for whatever reason - to generate a *.json file from a *.po translation file (eg. you want to use it in React as well), we found another script for you: https://github.com/mikeedwards/po2json (GNU Licence). Install it and add another script to your package.json similar to
po2json -f 'mf' src/wordpress/languages/plugin-name-en.po src/wordpress/languages/plugin-name-en.json
Note, you might have to adjust it to fit your individual needs, as currently en is the default input and output in this example.
If you are ready for production run yarn build (or npm run build). You can
then upload the entire dist folder to the WordPress svn repository of your plugin.
There are some technologies and packages we use, which we want to further highlight here:
| Technology | Description |
|---|---|
| React | React is a declarative, efficient, and flexible JavaScript library for building user interfaces. |
| react-intl | Internationalize React apps. |
| Redux | Predictable state container for JavaScript apps |
| Babel | Babel is a JavaScript transpiler that converts edge JavaScript into plain old ES5 JavaScript that can run in any browser (even the old ones). |
| Webpack | webpack is a module bundler. Its main purpose is to bundle JavaScript files for usage in a browser, yet it is also capable of transforming, bundling or packaging. |
| Jest | Jest is the de facto unit testing framework for ReactJS project. |
| Enzyme | JavaScript library for testing React components. |
| ESLint | Linting utility for JavaScript. |
| Prettier | Prettier is an opinionated code formatter. |
Stefan Natter |
Lukas Ender |
