Integrating Gutenberg Blocks in Existing WordPress Plugins

Gutenberg is coming and if your WordPress plugin is using shortcodes, you might consider building Gutenberg blocks out of the shortcodes. In this tutorial, we will not learn about converting shortcodes into Gutenberg blocks. We will learn how we can integrate Gutenberg blocks into your existing plugins.

In this tutorial, I will assume that you don’t have Webpack configured in your plugin and that this will be the first configuration in your plugin.

If you already have Webpack configured for your plugin, you will have to edit it, but it should not be too complex.

For this tutorial, the configuration will mostly refer to the GiveWP configuration so you can see a live (production) example on how you can integrate the blocks in your plugins.

The Environment

Before you can build Gutenberg Blocks, you will need to set up the environment. If you think of using the modern JavaScript, your setup will need to compile React JSX and ESNext (ES6, ES7+).

I will focus on using Webpack here and if you’ve never used Webpack before, I have another article on Configuring Webpack in WordPress for the First Time.

If you don’t use NPM and packages in your plugin, then make sure that you have npm available from your terminal (command prompt). If you don’t, you need to install Node.js.

Packages

We need to install npm packages that will be used to compile our JavaScript and CSS and also optimize them. There are also other packages that are used for something else such as creating .pot files and such.

Create a package.json in the root folder of your plugin and add this:

If you already have a package.json, take a look at the dependencies and add those that are missing. Place yourself in the root folder of your plugin using the terminal (command prompt) and run npm install so that all dependencies are installed.

Babel Config

When Babel compiles our JavaScript, it will look for a Babel configuration and if it’s there, it will use the rules for the compilation that are defined there. Create a file .babelrc and enter this:

We are defining that Babel when compiling React JSX, will use the Gutenberg Component wp.element.createElement instead of the default React.createElement. You are read more on editing Babel configuration here.

Git Ignore

If you’re using Git to version control your plugin, then you should ignore node_modules because it will get really huge and you don’t need that since you can install the packages anywhere using package.json.

Create a new file .gitignore and add this:

Webpack Configuration

If you don’t have Webpack yet, create a file webpack.config.js in the root folder of your plugin. If you understand Webpack, you can look at the whole configuration on gist.

Before going onwards, you should know that we’re using Webpack 3.12.0 and not the latest Webpack 4. Everything should be the same except the Extract Plugin. You can read the comment from my other article on configuring the Extract Plugin and Webpack CLI for 4.x.

Modules and Babel

Let’s now require the modules that we will use and create the constant config that will hold some of compilation rules.

We are making Webpack know that jQuery is globally available and it won’t be imported as a module. We are then creating a rule for .js files, except those in node_modules, to be compiled using Babel.

The plugins section allows us to include various plugins that are going to get called when compiling all the files. First, we are deleting the dist folder before comiling it again. We are extracting all the CSS to the css folder and we are also calling the RTL plugin to create RTL CSS.

Let’s now add the rules to compile CSS/SASS and Images.

CSS and Images in Webpack

When a JS file is importing a .scss, Webpack will load it using the provided rules and compile SASS to CSS. After it’s compiled, it will extract it to the css folder. The images mentioned in our CSS will also be moved to the images folder and optimized.

Input and Output Files

Webpack also requires entries and outputs. The entries are all the files that Webpack is compiling and such files will import other JS/CSS files.

In the first part, we are telling Webpack to look at the files located at assets/frontend and assets/backend. It is looking at both JS and SCSS. The keys backend and frontend will be used as the names for the compiled scripts and styles.

The output part is letting Webpack know where to put the compiled files. Here, all the files are going to be put inside assets/dist/js. The Extract Plugin will then move the CSS files to assets/dist/css.

The second part is related to Gutenberg. We will look at the load.js inside blocks folder to compile it and save it as assets/dist/gutenberg.js. Also, there will be another file babel-polyfill.js which you can enqueue before gutenberg.js if you’re using ES6+ features that need polyfills.

Production

When using our plugin in production, we should have CSS and JS minified. We should also have our plugin localized so creating .pot files is also a good thing.

That’s it. For now, this won’t work of course.

Folder Structure

For this Webpack configuration to work, we need to have a folder assets with folders frontend and backend. The scripts and styles there will be then compiled into the folder /assets/dist.

Also, create a folder blocks in the root folder of your plugin and create a load.js there. With that, you can now start writing Gutenberg blocks there.

Loading Gutenberg Blocks

We will also use a simple class to load our Gutenberg scripts. Let’s create a file blocks.php inside of the folder blocks and put this code:

If you include this file in your plugin, it will load the Gutenberg Blocks only if Gutenberg is installed and activated. You can also use this class to register new REST APIs that your blocks will use or anything else you need for your Gutenberg integration to work.

Conclusion

Integrating Gutenberg Blocks in existing WordPress plugins can be a complicated task, especially if you’ve never worked with Babel and compiling Modern JavaScript. I hope that with this tutorial, you’ll get an idea on how you can approach this and integrate your new Gutenberg Blocks in your plugin.

Have you already integrated Gutenberg in your Plugin? How was the process of it? Share with us in the comments below.

Become a Sponsor