WordPress Starter Plugin - React.js

Our goal here is to make plugin development easier with React. This structure stems from our WordPress Starter Plugin Vue, but has been reworked for React.

Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Setup
   • Clean Unused Files
   • Installation
3. Usage
4. Build Logic
5. UI Frameworks
6. Roadmap
7. Contributing
8. License
9. Contact
10. Acknowledgments

About The Project

WordPress plugin development is a cumbersome endeavor. This is much harder to manage when your background is Node.js and JavaScript, instead of Laravel and PHP. This boilerplate project will rapidly get you up and running with developing a new plugin.

In the spirit of a modern upgrade, we have built this into a TypeScript React plugin template.

(back to top)

Built With

• Node Version Manager (NVM)
• Node.js
• TypeScript
• React.js
• Vite
• SASS/SCSS
• Gulp.js
• ESLint
• Prettier

(back to top)

Getting Started

All plugin files live inside of the /src folder. These are the instructions on setting up your project locally. To get a local copy up and running follow these simple steps.

Prerequisites

For all of the awesome people using Node Version Manager (NVM) instead of Node.js, we have an .nvmrc file in the repo. For everyone else, please check this file to make sure that your Node.js version matches.

• Switch to correct Node.js Version

nvm use

Setup

Before you start working, you will need to rename all of the correct files, functions, assets, etc. BEFORE you run npm install. This setp is also about naming your plugin with your own namespacing.

1. Manually rename any files in the entire repo that are prefixed with wp-react-starter.
2. Search and replace the entire repo for any occurances of wp-react-starter.
3. Search and replace the entire repo for any occurances of wp_react_starter.
4. Search and replace the entire repo for any occurances of WPReactStarter.

Clean Unused Files

There are a few instances where you may not need the starting files and folder structure. In these instances, it's a good practice to delete them. Please see a few examples below.

1. i18n Languages: /src/languages

   • If you have no intentions to add multiple languages, also known as "internationalization" (or i18n for short), then you can delete this folder.

2. Public Front-End: /src/php/public

   • If the plugin you are developing doesn't have a need for front-end support, and is only used in the WP Admin area, then you can delete this folder.

3. TypeScript Types: /src/utils/types

   • If you don't end up adding to or updating this folder, then you can remove it.

4. TypeScript Enumerations: /src/utils/enums

   • If you don't end up adding to or updating this folder, then you can remove it.

5. TypeScript Interfaces: /src/utils/interfaces

   • If you don't end up adding to or updating this folder, then you can remove it.

6. Vue Components: /src/components

   • If you don't end up adding to or updating this folder, then you can remove it.

Installation

1. Clone the repo.

   git clone https://github.com/jared-leddy/wordpress-plugin-starter-react.git

2. Install NPM packages.

   npm install

3. Run the start command to watch and build files.

npm run start:dev

(back to top)

Usage

Below, you will find our common commands and notes for general usage.

1. Run npm run build:dev.

   • When you build in dev, the plugin folder IS NOT ZIPPED. This is for those situations where you're working with local instance of WordPress using XAMP, LAMP, MAMP, etc. or even the LocalWP tool (which we use). Those steps are:
     • Build the new plugin folder.
     • Delete the current folder in your WP website.
     • Copy your new plugin folder into the website's plugins folder.

2. Run npm run build:prod.

   • When you build in prod, the plugin folder IS ZIPPED and ready for upload to a WP website.

3. Run npm run start:dev.

   • This is runs the default vite command. The terminal will tell you to open the browser to a localhost port. We do not use the browser.
   • A custom hot reload plugin is located in the Vite config file to watch all files in the /src folder.
   • Each time a file is changed, the hot reload will trigger a npm run build:dev.

4. The admin/index.php is the base PHP template for the plugin settings admin page UI. It has an element <div id="app"></div> where the Vue app is getting mounted.

5. The provided Vue template can be found in src/vue/App.vue.

(back to top)

Build Logic

Vite Build

Vite will convert all of your .ts to .js and all .scss to .css. THey will all be placed in a /dist folder.

Build Package

This covers the series of tasks that are used to initially build the plugin folder. Found in both build:dev and build:prod scripts.

1. Verify Folders Exist

   • Here, we are checking to see if you have manually created your plugin folder. If you have not already created your plugin folder, we will create one for you.
   • This folder needs to be present for subsequent tasks.

2. Copy Files to Folder

   • Here, we are copying your entire /src folder contents into your plugin folder.

3. Move Assets from Dist

   • Vite is run before Gulp. All of your .js and .css files will be located there.
   • For this task, those files built into the /dist folder get moved into your plugin folder.

Clean Package

This covers the series of tasks that are used to clean up the plugin folder. Found in both build:dev and build:prod scripts.

1. Delete Trivial Files
   • Here, we delete all of the trivial files.

A trivial file typically refers to a file that contains very little or no meaningful content. These files often have minimal or placeholder code, which serves little purpose in the context of a larger project. In the context of software builds and packaging, trivial files are usually considered unnecessary and can be removed to optimize the final package.

Here are some common examples of trivial files:

• Empty files: Files that have no content at all.
• Export placeholder files: Files that contain only trivial exports like export {};, often created to satisfy module systems but don't serve any real purpose.
• Files with a single constant or trivial content: For example, a file that only defines a single constant but is never used meaningfully. See examples below:

Empty File:

// This is a completely empty file

Export Placeholder:

export {};

Trivial Content:

const someVar = 'value'; // A single trivial statement with no broader impact

Removing these files can help reduce clutter, decrease the size of your final builds, and improve overall project performance.

2. Delete TypeScript Files

   • Delete all files with a .ts extension from the plugin folder . We have already used Vite to build these .js files, so we don't need to retain them.

3. Delete SCSS Files

   • Delete all files with a .scss extension from the plugin folder . We have already used Vite to build these .css files, so we don't need to retain them.

4. Clean PHP Folder

   • The majority of our PHP is located in /src/php.
   • During the move step above, we are moving this php folder into out plugin folder.
     • Example: /wp-react-starter/php
   • Here in this task, we will move all of those contents up a tree level (i.e., to /wp-react-starter).
   • This step will leave an empty php folder intentionally.

5. Delete Empty Folders

   • Deleting files out of our plugin folder, and moving the PHP files up a level, will leave empty folders lying around.
   • Here, we will recursively delete all empty folders from the parent plugin folder (i.e., /wp-react-starter).

Clean Project

This covers the series of tasks that are used to clean up the plugin folder after the zip file is created. Found in both build:dev and build:prod scripts.

1. Delete Folders

   • Delete the /dist folder that is generated by Vite.
   • Delete the plugin folder (i.e., /wp-react-starter).

Zip Project

For this one, we will "compress" or "zip" the plugin folder. This is the step that will produce the final plugin zip file that you upload into the WordPress website. Since this one is just a task, we don't have a need to do anything more than zip the folder.

Found in build:prod script.

(back to top)

UI Frameworks

As we go through and develop our own plugins using these frameworks, we will document what UI frameworks are working with this starter template.

Works Well

• Bootstrap

Has Problems

• Naive UI

  • We tried using this in an admin-only plugin, but had issues trying to keep Vue loaded. There is an open issue for extensive testing.

• Vuetify

  • We tried using this in an admin-only plugin, but ended up having to use !important in all of our styles. That's not the best use of a framework like this. There is an open issue for extensive testing.

Not Tested

• Bootstrap Vue

(back to top)

Roadmap

We don't have a dedicated roadmap outside of Github. Simply check the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.md for more information.

(back to top)

Contact

X @jaredleddy

Carbon Digital

Project Link: https://github.com/jared-leddy/wordpress-plugin-starter-react

(back to top)

Acknowledgments

Without these people and tools, life would be too complicated.

• Good food.
  • Steak 🥩
  • Ramen 🍜
  • Rice 🍚
  • Tacos 🌮
  • Breakfast Burritos 🌯
  • Burgers 🍔
  • Pizza 🍕
  • Coffee ☕
• Good company.
  • Family 👫 👨‍🍼
  • Friends 👨‍🏫 👨‍🚀 🏋️‍♂️ ⛹️‍♂️ 🏄‍♂️ 🏌️‍♂️ 🏂 🤺 🧗‍♂️ 🏃‍♂️ 🎣
• Good tools.
  • VS Code
  • Node Version Manager (NVM)
  • Warp Terminal

(back to top)