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 💥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
Table of Contents
- Install the required modules with
- start the docker containers with
cd docker && docker-compose up
- and finally watch for changes or build the client bundle with
- 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.
- 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
srcfolder to match it with your plugin name. We will add a script for this later on.
- You also have to rename all files including
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
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
WordPress REST API
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.
Plugin Settings Page
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.
i18n Translation in WordPress
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.
i18n Translation in React
To enable translations in React we use react-intl.
How to 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.
How to extract and generate json files for each language
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
How to translate and use translation
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,
is capable of doing this!
Additonal scripts and help
To generate only one default language (currently en) file called
yarn i18n:generate-default-language after you built the app with
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:
|react-intl||Internationalize React apps.|
|Jest||Jest is the de facto unit testing framework for ReactJS project.|
|Prettier||Prettier is an opinionated code formatter.|