{"id":18044735,"url":"https://github.com/natterstefan/react-wordpress-plugin","last_synced_at":"2025-04-10T01:12:06.209Z","repository":{"id":52972148,"uuid":"135822531","full_name":"natterstefan/react-wordpress-plugin","owner":"natterstefan","description":"React WordPress Plugin Boilerplate with a React admin interface and a Docker Development Setup.","archived":false,"fork":false,"pushed_at":"2021-04-11T21:42:36.000Z","size":193,"stargazers_count":15,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T01:12:01.277Z","etag":null,"topics":["docker","react","wordpress","wordpress-boilerplate","wordpress-development","wordpress-plugin"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/natterstefan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-02T14:03:32.000Z","updated_at":"2024-04-18T21:07:52.000Z","dependencies_parsed_at":"2022-09-03T04:52:20.876Z","dependency_job_id":null,"html_url":"https://github.com/natterstefan/react-wordpress-plugin","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natterstefan%2Freact-wordpress-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natterstefan%2Freact-wordpress-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natterstefan%2Freact-wordpress-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natterstefan%2Freact-wordpress-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/natterstefan","download_url":"https://codeload.github.com/natterstefan/react-wordpress-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137888,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","react","wordpress","wordpress-boilerplate","wordpress-development","wordpress-plugin"],"created_at":"2024-10-30T18:10:30.625Z","updated_at":"2025-04-10T01:12:06.190Z","avatar_url":"https://github.com/natterstefan.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React-WordPress-Plugin\n\n[![Build Status](https://travis-ci.org/natterstefan/react-wordpress-plugin.svg?branch=master)](https://travis-ci.org/natterstefan/react-wordpress-plugin)\n[![GitHub issues](https://img.shields.io/github/issues/natterstefan/react-wordpress-plugin.svg)](https://github.com/natterstefan/react-wordpress-plugin/issues)\n[![Dependencies](https://img.shields.io/david/natterstefan/react-wordpress-plugin.svg)](https://github.com/natterstefan/react-wordpress-plugin/blob/master/package.json)\n[![DevDependencies](https://img.shields.io/david/dev/natterstefan/react-wordpress-plugin.svg)](https://github.com/natterstefan/react-wordpress-plugin/blob/master/package.json)\n[![Known Vulnerabilities](https://snyk.io/test/github/natterstefan/react-wordpress-plugin/badge.svg)](https://snyk.io/test/github/natterstefan/react-wordpress-plugin)\n[![GitHub license](https://img.shields.io/github/license/natterstefan/react-wordpress-plugin.svg)](https://github.com/natterstefan/react-wordpress-plugin/blob/master/LICENCE)\n\nReact-WordPress-Plugin is a WordPress Plugin boilerplate with React on both the\nadmin page and React component rendering on the public page alongside a fully\nfunctionally WordPress plugin.\n\n### Features\n\nThis boilerplate plugin provides certain out-of-the-box features for both development\nand production:\n\n* :tada: WordPress plugin boilerplate with\n  * :arrows_counterclockwise: already built-in [WordPress hooks](https://codex.wordpress.org/Plugin_API/Hooks)\n    (eg. activation and deactivation hooks)\n  * :twisted_rightwards_arrows: [WordPress REST-API endpoint](https://developer.wordpress.org/rest-api/)\n    which is already used by the React App\n  * :pencil: plugin options handling with WordPress's [Options API](https://codex.wordpress.org/Options_API)\n    (eg. store data in the WordPress database)\n  * :page_with_curl: plugin settings page in wp-admin\n* :boom: Sample React-App with example components on the plugin settings-page\n* :earth_americas: i18n support for both [React](#i18n-translation-in-react)\n  and [WordPress](\u003c(#i18n-translation-in-wordpress)\u003e), with sample translation\n  \\*.pot template file\n* :rocket: Webpack, react-intl, ESLint, Stylelint and Prettier and other [awesome\n  technologies](#technology-stack)\n\n\u003c!-- TOC --\u003e\n\n## Table of Contents\n\n* [React-WordPress-Plugin](#react-wordpress-plugin)\n  * [Requirements](#requirements)\n  * [Quickstart](#quickstart)\n    * [Debug Mode](#debug-mode)\n    * [Troubleshooting](#troubleshooting)\n  * [Development](#development)\n    * [Introduction and Overview](#introduction-and-overview)\n    * [Folder Structure](#folder-structure)\n    * [WordPress REST API](#wordpress-rest-api)\n    * [Plugin Settings Page](#plugin-settings-page)\n    * [i18n Translation in WordPress](#i18n-translation-in-wordpress)\n    * [i18n Translation in React](#i18n-translation-in-react)\n  * [Deployment](#deployment)\n  * [Technology Stack](#technology-stack)\n  * [Maintainers](#maintainers)\n\n\u003c!-- /TOC --\u003e\n\n## Requirements\n\n* Install [Node 8.11.1 or greater](https://nodejs.org)\n* Install [Yarn](https://yarnpkg.com/en/docs/install) (min. 1.3.2, or\n  [npm](https://www.npmjs.com/get-npm) if you prefer)\n* Install [Docker](https://www.docker.com/get-docker)\n\n## Quickstart\n\n1.  Install the required modules with `yarn` (or `npm install`),\n2.  start the docker containers with `cd docker \u0026\u0026 docker-compose up`\n3.  and finally watch for changes or build the client bundle with `yarn watch`\n    or `yarn build`.\n4.  Now open http://localhost:8000, set up WordPress and activate the plugin.\n5.  Finally you can then see the admin page on http://localhost:8000/wp-admin/admin.php?page=plugin-name\n\nTo improve the coding experience and efficiency there are helpful scripts\navailable, see [package.json](package.json) for more details.\n\n**Additional Notes:**\n\n* Docker has to run in order to develop!\n* A docker compose file is provided for local development and testing, see\n  [docker/README](docker/README.md).\n* Currently you have to rename `PLUGINNAME` and `plugin-name` in the `src` folder\n  to match it with your plugin name. We will add a script for this later on.\n* You also have to rename all files including `plugin-name`\n  (eg. [plugin-name.php](src/wordpress/plugin-name.php))\n\n### Debug Mode\n\nTo enable logging in your browser, you have to enter debug mode by running\n`localStorage.setItem('debug', '*')` in your browser's console.\n\n### Troubleshooting\n\n* _changes are not visible or plugin is deactivated_: just re-start the docker\n  image and the `yarn watch` script\n\n## Development\n\n### Folder Structure\n\nGenerally we have put both React and WordPress into their own subfolder for\nbetter maintainability.\n\n```\n/src/react \u003c\u003c contains React related code (eg. components)\n/src/static \u003c\u003c contains static files like images for both React and/or WordPress\n/src/wordpress \u003c\u003c contains WordPress plugin related code (eg. hooks, actions)\n```\n\nThe current boilerplate setup of WordPress is more \"sophisticated\". This is the\nreason why we will talk more about it's folder structure.\n\n```\nadmin/ \u003c\u003c contains code relevant in wp-admin (eg. settings-page)\nincludes/ \u003c\u003c contains i18n, activator and deactivator, generally speaking helpers and plugin wide classes/features\nlanguages/ \u003c\u003c i18n translation files\npublic/ \u003c\u003c contains code relevant for the public site of the WordPress instance\nstatic/ \u003c\u003c images and other static assets\nplugin-name.php \u003c\u003c initialises the Plugin and defines Constants\nREADME.txt \u003c\u003c describe the plugin, certain features, FAQ and other details\nuninstall.php \u003c\u003c will be triggered when the plugin will be uninstalled\n```\n\n### WordPress REST API\n\nTo interact with the WordPress database React needs to interact with a WordPress\nREST API. We have already included an example controller class in this boilerplate.\nWe followed the guideline and examples in the [WordPress developer documentation](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/).\nPlease take a look at it to familiarise yourself with the topic. You will need\nto create new endpoints or enhance existing ones to enable React to talk with\nWordPress and update data.\n\n### Plugin Settings Page\n\nThe boilerplate also includes the creation and setup of a wp-admin menu page.\nThe admin class (see [admin/class-admin.php](src/wordpress/admin/class-admin.php))\ntakes care of adding a menu page and rendering a DOM node for the React app by\nincluding [views/admin-index.php](src/wordpress/admin/views/admin-index.php).\nFrom there you can develop the React app in [react/admin.js](src/react/admin.js)\nand follow React best practices.\n\n### i18n Translation in WordPress\n\nOne can easily start translating the WordPress plugin (php-codebase) by first\nreading the WordPress [developer documentation](https://developer.wordpress.org/themes/functionality/localization/)\nand the [i18n for WordPress Developers](https://codex.wordpress.org/I18n_for_WordPress_Developers)\nbefore following the documentation here: https://wordpress.stackexchange.com/a/258562.\n\nEventually you will run a command similar to this one to create a pot file:\n\n```\ncd wpdev/tools/i18n\nphp makepot.php wp-plugin ../../../react-wordpress-plugin/src/wordpress/ plugin-name.pot\n```\n\nFrom there you can start translating with our preferred editor [PoEdit](https://poedit.net/download)\n(availble for both Mac and Windows) for instance.\n\n### i18n Translation in React\n\nTo enable translations in React we use [react-intl](https://github.com/yahoo/react-intl).\n\n#### How to use react-intl\n\nSimply use the following components and methods from react-intl:\n[defineMessages()](https://github.com/yahoo/react-intl/wiki/API#definemessages),\n[\u003cFormattedMessage\\\u003e](https://github.com/yahoo/react-intl/wiki/Components#formattedmessage), and\n[\u003cFormattedHTMLMessage\\\u003e](https://github.com/yahoo/react-intl/wiki/Components#formattedhtmlmessage)\nin your components. Check out the example in the [App](src/components/app/index.js)\ncomponent to get started.\n\n#### How to extract and generate json files for each language\n\nOnce you have added some translation strings, you can generate the necessary files\nto start translating. To create the translation files run either `yarn watch` or\n`yarn client`. [babel-plugin-react-intl](https://github.com/yahoo/babel-plugin-react-intl)\nwill then create the `*.json` files (by extracting the default message descriptors)\nfor each language and our [i18n webpack plugin](webpack/plugins/i18n.js) will do\nthe rest (eg. copy it into `dist/static/languages`).\n\n#### How to translate and use translation\n\nAll you have to do now is translating the generated \\*.json files (see\n`/dist/static/languages/*.json`) and putting them back into the static folder\nbefore releasing your plugin.\n\n**Attention:** babel-plugin-react-intl will overwrite the translation files in\n`dist/static/languages` everytime it runs. This should be improved in the future,\nas [react-intl-translations-manager](https://www.npmjs.com/package/react-intl-translations-manager)\nis capable of doing this!\n\n#### Additonal scripts and help\n\nTo generate only one default language (currently en) file called `en.json` run\n`yarn i18n:generate-default-language` _after_ you built the app with `yarn build`.\n\nBecause `yarn build` uses the custom made webpack plugin to create multiple\ntranslation files for multiple languages (see [webpack/common.config.js](webpack/common.config.js)).\nWith the command above you can overwrite it.\n\nIf you need - for whatever reason - to generate a \\*.json file from a \\*.po\ntranslation file (eg. you want to use it in React as well), we found another\nscript for you: https://github.com/mikeedwards/po2json (GNU Licence). Install it\nand add another script to your package.json similar to\n\n```\npo2json -f 'mf' src/wordpress/languages/plugin-name-en.po src/wordpress/languages/plugin-name-en.json\n```\n\nNote, you might have to adjust it to fit your individual needs, as currently en\nis the default input and output in this example.\n\n## Deployment\n\nIf you are ready for production run `yarn build` (or `npm run build`). You can\nthen upload the entire `dist` folder to the WordPress svn repository of your plugin.\n\n## Technology Stack\n\nThere are some technologies and packages we use, which we want to further highlight\nhere:\n\n| Technology                                        | Description                                                                                                                                                        |\n| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| [React](https://facebook.github.io/react/)        | React is a declarative, efficient, and flexible JavaScript library for building user interfaces.                                                                   |\n| [react-intl](https://github.com/yahoo/react-intl) | Internationalize React apps.                                                                                                                                       |\n| [Redux](https://github.com/reduxjs/redux)         | Predictable state container for JavaScript apps                                                                                                                    |\n| [Babel](http://babeljs.io)                        | Babel is a JavaScript transpiler that converts edge JavaScript into plain old ES5 JavaScript that can run in any browser (even the old ones).                      |\n| [Webpack](http://webpack.js.org)                  | 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. |\n| [Jest](https://facebook.github.io/jest/)          | Jest is the de facto unit testing framework for ReactJS project.                                                                                                   |\n| [Enzyme](https://github.com/airbnb/enzyme)        | JavaScript library for testing React components.                                                                                                                   |\n| [ESLint](http://eslint.org/)                      | Linting utility for JavaScript.                                                                                                                                    |\n| [Prettier](https://github.com/prettier/prettier)  | Prettier is an opinionated code formatter.                                                                                                                         |\n\n## Maintainers\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/natterstefan\"\u003e\n          \u003cimg width=\"150\" height=\"150\" src=\"https://github.com/natterstefan.png?v=3\u0026s=150\"\u003e\n          \u003c/br\u003e\n          Stefan Natter\n        \u003c/a\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/lumannnn\"\u003e\n          \u003cimg width=\"150\" height=\"150\" src=\"https://github.com/lumannnn.png?v=3\u0026s=150\"\u003e\n          \u003c/br\u003e\n          Lukas Ender\n        \u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003ctbody\u003e\n\u003c/table\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatterstefan%2Freact-wordpress-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnatterstefan%2Freact-wordpress-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatterstefan%2Freact-wordpress-plugin/lists"}