The WordPress Block Editor Plugin Boilerplate

The development in WordPress is being modernized by leaps and bounds. A few days ago I explained the current technologies that are already present in version 5 of our content management system. Now it’s time to teach you how to develop plugins for WordPress taking into account the possibilities of the new block editor.

Today I’ll describe the boilerplate that we are using in Nelio for our WordPress developments with a JavaScript base.

You have all the codebase of our boilerplate plugin for WordPress in GitHub, so you have no excuse to not modernize and expand your horizons as a developer.

WordPress Block Editor Boilerplate

The main reason for creating a project that serves as the basis for the creation of new WordPress plugins arises from our own need as developers to be able to unify and standardize all our projects.

Inspired by the WordPress Plugin Boilerplate, our idea is to do something similar but focused on plugins that extend the block editor with a modern stack using compilers, transpilers, bundlers and, ultimately, common development tools for JavaScript projects.

Installation And Development Process

The plugin boilerplate that we have created as a base can be downloaded directly from GitHub. After that, you can move it to the plugins folder (/wp-content/plugins/) of your WordPress installation:

git clone https://github.com/avillegasn/wp-beb.git

This will download the plugin folder with all the content. Then you need to rename both this folder and its content to use the name you want. For example, if your plugin is going to be called my-plugin:

• rename the wp-beb files to my-plugin
• replace wp-beb with my-plugin
• replace wp_beb with my_plugin
• replace WP_BEB with MY_PLUGIN

Once you have done this, to compile the plugin and generate the final code, run this:

npm install && npm run build

Keep in mind that you will need to have installed the following tools:

• Node.js v8.9.1 or later.
• npm v5.5.1 or later.
• Composer v1.8.1 or later.

The npm install command downloads the dependencies of Node.js and PHP in the node_modules and vendor folders, respectively. When the process finishes you will have a dist folder with the compiled files. Now it is safe to activate the plugin in your WordPress.

In addition to the previous command, our boilerplate provides the following additional commands:

• npm run dev Build files without minification.
• npm run watch Build files and watch for changes.
• npm run build Build files and minify JS and CSS.
• npm run lint-php Run PHP_CodeSniffer on PHP files to detect errors.
• npm run lint-php:fix Run phpcbf to try to fix PHP errors.
• npm run lint-css Run stylelint on SCSS files to detect errors.
• npm run lint-css:fix Try to fix errors on SCSS files.
• npm run lint-js Run eslint on JS files to detect errors.
• npm run lint-js:fix Try to fix errors on JS files.
• npm run lint Run linting process on PHP, SCSS, and JS files.
• npm run update:packages Update package dependencies in Node.js.

Usually you’ll be running npm run watch while you are developing code so that changes are compiled and bundled in real time. To generate a final, stable version, though, run npm run build.

Nelio A/B Testing

Native Tests for WordPress

Use your WordPress page editor to create variants and run powerful tests with just a few clicks. No coding skills required.

More Info

Contents And Folder Structure

Our WordPress Block Editor Boilerplate includes the following files and folders:

• .babelrc. Babel configuration file.
• .editorconfig. EditorConfig file that helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs.
• .eslintignore. Used to exclude certain files from ESLint linting process.
• .eslintrc. ESLint config file.
• .gitattributes. Text file that gives attributes to path names in Git.
• .gitignore. Used to exclude certain files from the repository.
  composer.json. Describes the PHP dependencies of the project and may contain other metadata as well.
• composer.lock. Used to lock multiple developers working on the same project to the same versions of PHP dependencies.
  index.php. To hide the inner file structure in the server, whatever that be.
• LICENSE.txt. Copy of the GNU GPL v2 license.
• package-lock.json. Used to lock multiple developers working on the same project to the same versions of NPM dependencies.
• package.json. Manifest file for the project. Central repository of configuration where you will find the names of the packages required and the CLI commands you can use to manage the project.
• phpcs.ruleset.xml. PHP_CodeSniffer config file.
• postcss.config.js. PostCSS config file.
• README.md. The file that you’re currently reading.
• readme.txt. The template for the WordPress plugin readme file.
• webpack.config.js. Config file for webpack.
• wp-beb.php. Main file of the WordPress plugin.
• An assets directory that contains CSS, JS, and image resources.
• A languages directory that contains the translation files for i18n.
• A packages directory that contains block definitions to extend the WordPress block editor.

Apart from all this, once you compile the project, you will get the dist folder with the compiled files, the vendor directory with dependencies and executables for PHP, and the node_modules directory with dependencies and executables for NPM and JavaScript.

Add a New Block to The WordPress Block Editor

The interesting thing about this WordPress Block Editor Boilerplate is its default state. Once you have downloaded and compiled the plugin activate it and you’ll discover that it’s a fully functional plugin that adds a new block in your editor.

The Demo block added by our boilerplate is just a simple text block preceded by a heart dashicon, as you can see in the previous screenshot. The block also defines two additional styles, which modify the colors of the text inside the block. These should help you understand how to create blocks and styles in Gutenberg.

The JavaScript code that adds this block in the editor is in packages/blocks/demo (see here). If you want to delete this block, just delete the demo directory and delete its import and usage in the packages/blocks/index.js file.

In addition, the code for the demo block is split into different files, each of these including a different portion of the arguments used by registerBlockType.

On the other hand, if you want to add an additional block, duplicate the packages/blocks/demo and give it the name you want for your block. Modify the JavaScript files inside as you wish and remember to import the main file of the new block in packages/blocks/index.js.

Extend The Block Editor With a Plugin

In addition to the demo block that I mentioned before, our boilerplate for the block editor includes the definition of a Gutenberg plugin. Keep in mind that this “plugin” is not a regular WordPress plugin, but something that extends the block editor itself. “A plugin inside the WordPress plugin”, if you will.

You can see the plugin in the screenshot above, located on the right side. This plugin is activated by clicking on the icon on the top right, next to the publish button.

The plugin includes a color picker (so you can see how you can easily reuse the React components that Gutenberg includes) and a button to insert a demo block to the editor programmatically (another interesting scenario).

You have the plugin code in assets/src/js/admin (you can see it here). Specifically, the file plugin.js includes the call registerPlugin and the file plugin-component.js defines the component that is responsible for rendering the color picker and the button that I mentioned before.

Again, you can modify this plugin as you wish. Or you can delete it, if you want. To do so, remember to remove the plugin.js JavaScript file enqueued in the main file wp-beb.php (see here) as well as the corresponding CSS file (here).

Let’s Give it a Shot!

We hope that our WordPress Block Editor Boilerplate will help you to get rid of your JS fear and to start programming extensions for the WordPress block editor in a simple way. Try it and tell us about your experience. We will be happy to read your comments!

Featured image by Icons8 team on Unsplash.