Introducing Gutenberg Boilerplate For Third Party Custom Blocks!

Gutenberg is all that you hear about in the WordPress community nowadays. Everyone is writing articles on how they feel about Gutenberg. I was one of the early adopters and contributors in the Gutenberg project.

I have had been writing about it (invitation to contribute) and covering the meeting notes for the project. When folks started writing about Gutenberg I wanted to do the same, but I was on vacations, visiting my parents, and enjoying Eid holidays. But that’s not all; I stopped myself from writing anything because I have been a bit confused.

I am still making up my mind with how Gutenberg will fit in the WordPress core. There are so many things which are both good and bad about it. So, instead of ranting about it, I wanted to do something more productive. And I went ahead, studied the source code, received a lot of help from Gutenberg contributors (Matias Ventura, James Nylen, Riad Benguella, Andrew Duthie, Joen, etc.) to finally build a Gutenberg Boilerplate project.

After being a contributor to the project and having tried to build this Gutenberg boilerplate I have been able to read through almost 80% of the code base. While Gutenberg is changing at a fast pace (five releases in the last 29 days) there are things about this project that are not going to change!

Here’s what I think about Gutenberg (v0.5.0)

✔️ PRO’s: The Concept of a Block

• Gutenberg is a neat initiative. The editor needs to be improved.
• Blocks are way better than those dayum shortcodes!

❌ CON’s: The Concept of a Block

• Not sure if we are trying to reinvent the wheel maybe as a block? Does EVERYthing fit in a block?

✔️ PRO’s: ReactJS, ESNext, Webpack

• Using a cutting edge language like ReactJS definitely, means that we are fighting the tech-debt with WordPress and that it’s a beginning of new things.
• Imagine if both ReactJS and the WP REST API are in the core.
• We could improve a lot of things that way. Ryan already has a proof of concept with new list tables based on ReactJS and REST API.

❌ CON’s: ReactJS, ESNext, Webpack

• WordPress is not easy anymore.
• Well, scratch that. WordPress development just became very complicated with the Gutenberg project.
• There are a lot of things that should be decided by more than a few developers who know ReactJS, ESNext, Webpack, and modern tooling.
• The fact is, there aren’t many who know the ropes around here. Let alone interested in contributing to this project. Which leaves us with scary conclusions?

✔️ PRO’s: NPM Packages

• We can start using NPM packages for WordPress development now.
• As a developer who writes NodeJS code off and on, it can be a possible step to improve my NodeJS skills once in for all.

❌ CON’s: NPM Packages

• When using NPM Packages, who and how do we decide which package should be utilized?
• Do we have ReactJS/NodeJS coding standards?
• It’s way too hard for a beginner developer to understand let alone write this kind of code.

🙄 CONCERN: The Dependency Hell#

With the inclusion of ReactJS, Webpack, ESNext, and NPM packages into the development of WordPress core and obviously for third party plugins there is a huge concern of what they call The Dependency Hell™.

• The Cost of (63+671) Modules: All these dependencies cause problems! There are 63 NPM modules with 671 children module dependencies which are 106 MB in size. I’ve put the detailed info in a gist for the geeks.
• API Concerns: The API being built over these dependencies can have a lot of problems at scale! WordPress is a public facing software after all. It’s not a SaaS managed by a team of pro developers.
• Looks like there are 98 modules from Sindre Sorhus — while he’s a good friend and an awesome developer. The concern here is dependency!

• License Paradox: There is also the issue of GPL compatible licenses. I did a cursory scan of modules to build a license list at Codepen for the Gutenberg editor project at version 0.5.0.
• I am not a lawyer, so, I’ll just raise a valid concern here — Are these licenses GPL compatible? Will all the sub module licenses by GPL compatible? What are we doing to make sure of that?

I have more to say, but I’ll stop here! Let’s be more productive and build something!

Gutenberg Boilerplate is a WordPress plugin that demonstrates how you can develop custom Gutenberg blocks both with and without a build process.

🌟 IMPORTANT:

Before we dive in — I recommend you star the GitHub repository for Gutenberg Boilerplate. To show support and to keep up with the updates — with time this article may become outdated but not the repository!

⚡️ Getting Started#

Gutenberg Boilerplate is a WordPress plugin. So, go ahead, install the Gutenberg WP plugin and then download and install Gutenberg Boilerplate ZIP. Below you’ll find the information about these blocks, and their block.js files, while other files — I expect you to read them on your own.

⚡️ What Can You Learn?#

You can learn to build four different kinds of custom Gutenberg blocks at the time of release. These blocks are explained below:

• Build a Custom Gutenberg Block
  — with custom CSS for editor and frontend.
• Build a Custom Gutenberg Block
  — with ES6 or ESNext and a Webpack build process.
• Build a Custom Gutenberg Block
  — with editable content.
• Build a Custom Gutenberg Block
  — to click Tweet the contents of that block.

This is basically a Hello World example of building a custom block. It has the following file structure:

• block.js — We register Custom Gutenberg block here.
• editor.css _ Block CSS for the editor.
• style.css — Block CSS for the front end.
• index.php — Enqueue block’s assets for the editor and the front end.

Here’s how the block.js file looks. The inline documentation should be enough for you to understand what’s going on in there.

And here’s the index.php file where we enqueue assets.

Guess you can figure out how the CSS files would look like. Anywho, here it is.

This is basically a Hello World example of building a custom block with a build process and using ESNext, Webpack, Babel, etc.

It has the following file structure:

• block.js — We register Custom Gutenberg block here.
• block.build.js — Built file from block.js via NPM Script and Webpack.
• editor.css _ Block CSS for the editor.
• style.css — Block CSS for the front end.
• index.php — Enqueue block’s assets for the editor and the front end.
• .babelrc — Babel custom configuration.
• .gitignore — Gitignore file to ignore node_modules and such other files.
• package.json & package-lock.json — NPM related file for holding NPM related metadata and build/dev NPM scripts.
• webpack.config.js — Webpack configuration file.

Here’s the block.js filewritten in ESNext.

↣ The Build Process#

Read the files explained above. All of the files are heavily inline documented. All you have to do is following:

• Open up your favorite terminal app.
• Makes sure NodeJS and NPM are installed by running node -v or npm -v to check their versions.
• Access this directory cd /path/to/gutenberg-boilerplate/block/02-basic-esnext/
• Install node dependencies by running node install or sudo node install
• For building the block.jsfileinto block.build.js you can use run npm scripts.
• To watch and build run npm run dev
• To build for production run npm run build

Build process starts with the package.json file.

I have also written a very basic Webpack configuration. It’s explained inside the Webpack.congif.js file.

This is a basic Editable custom Gutenberg block.

It has the following file structure:

• block.js — We register Custom Gutenberg block here.
• editor.css _ Block CSS for the editor.
• style.css — Block CSS for the front end.
• index.php — Enqueue block’s assets for the editor and the front end.

Again, here’s the block.js file.

Fancy building a custom block to tweet content written inside it? Maybe you have already built a shortcode like this one before. Well, you’re in luck because I have built just that.

It has the following file structure:

• block.js — We register Custom Gutenberg block here.
• editor.css _ Block CSS for the editor.
• style.css — Block CSS for the front end.
• index.php — Enqueue block’s assets for the editor and the front end.

And here’s the custom block.js file!

This is all for now. I am hoping for you to have enjoyed this post. Go ahead and read the source code. Again, this post can go stale at a later date but I will try to keep the GitHub repository up to date. You should probably 🌟 star it. I have mixed feelings about this Gutenberg project.

• At one hand, it will make for a new an incredible WordPress Editor and will make developers happy for using ReactJS and new cutting edge modern tooling.
• On the other hand, it will confuse a lot of users and will make life harder for developers. Especially for those who make extensive use of meta boxes in their themes and plugins.

I’d like your comments about this. Do let me know if you have any thoughts or considerations about Gutenberg & its boilerplate. No pressure!

Gutenberg Boilerplate Updates#

• 🌟 The GitHub repo now has 778 stargazers/watchers/forks!
• 🎉 Gutenberg Boilerplate got featured at WPTavern — Thanks, Sarah!
• 🙌 Made it to “Picks of the Week” in WPWeekly #282 — Thanks, Jeff!

JUST A NOTE!
👨‍💻 I’m teaching thousands of devs how to become VSCode Power Users →
✅ This site is super fast?! It’s hosted with Kinsta on Google servers →