Introducing Gutenberg Boilerplate For Third Party Custom Blocks!
Ahmad Awais
β οΈGutenberg Boilerplate has been deprecated in favor of create-guten-block. Go ahead π and use
create-guten-block β
I have built a Gutenberg boilerplate to help WordPress theme and plugin developers kick-start their development with the new editor in town. It’s heavily inline documented. This post also contains my thoughts and concerns about the Gutenberg project.
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 β
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.
π€ My Thoughts about Gutenberg!#
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:
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:
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.js
fileinto 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!
If you’d like to get insights into professional full stack development, DevOps, WordPress community news, growing up a family, building and bootstrapping a business then subscribe to our premium newsletter called β£
The WordPress Takeaway!
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 β
π¨
Developers Takeaway
Stay ahead in the web dev community with Ahmad's expert insights on open-source, developer relations, dev-tools, and side-hustles. Insider-email-only-content. Don't miss out - subscirbe for a dose of professional advice and a dash of humor. No spam, pinky-promise!
β¨ 172,438 Developers Already Subscribed
Anything that gets merged with WordPress potentially influences the sites of millions of WordPress users. Gutenberg is another such project. While it looks neat, the endless possibilities begins with the inclusion of ReactJS, Webpack.
WP users should take part in improving the editor and making their say count. Or else, it’s gonna affect them in the long run.
You’re right about that!
What you show here looks to much more complicated than using acf flexible content fields to make a site modular. Do you agree?
Obviously, it is. Complicated and advanced!
Awesome write up and great examples!
That’s very kind of you to say! π― β Jason!
Hi! What about current themes and plugins that rely on shortcodes. Will they have problems in future?
Not sure about that! If anyone needs to start this discussion β NOW β might be the right time to do so. Gutenberg is planned to be merged in WordPress 5.0 with at least 100k installs of this plugin!
Woe to the users of Visual Composer, Divi, Avada, etc. I don’t use or recommend these but you only have to look on the Envato Marketplace to see how many people this could impact negatively. They’re potentially in for a ride and probably have no idea. If they end of having to redo their entire sites, they may decide to switch platforms?
Exactly, what happened with Drupal 8.0. They made it so hard for everyone that people just left it and moved to Laravel, Symphony, etc.
This would a disaster, as many of the people using Visual Composer, Divi, Avada, etc. are using it because they don’t know anything about coding. They would have to look at other options for non-coders such as Square Space or Wix to “rebuild” their sites. It would be a shame for these users to have leave WordPress.
Matt M. is clearly fighting SquareSpace and Wix with the Gutenberg push with little to no concern about backwards compatibility of the plugins, themes, builders and developers that made WordPress as popular as it is today. Gutenberg will kill WordPress as we know it, drive many devs, designers and small businesses away. Can they not fork WordPress at this point. Then this whole concern would be a moot point. Let Matt and Gutenberg go on their merry way conquering new market share why the rest of us continue to use and develop WordPress “Pro” (no-gutenberg core). But no, Matt’s hell bent on Gutenberg.
The interesting thing I picked up from this article is the complexity of the coding on the back end. One thing that allowed WordPress to be so adoptable in the early days was not only its ease of customization, many themes and infinite plugins, but how easy it was to code on the back end. That’s why many designers were able to pick up some coding and use WP. Now that advantage is gone and with it what made WP accessible.
I wish I could say I disagreed even having watched everything from WordCamp US 2017. I hope that things aren’t nearly as dire as what you describe but that’s merely wishful thinking on my part. Developers may be able to adapt in time but the non coders will only be saved if the solutions they depend on can be migrated in time. This is possible but unlikely, I’d say.
Hi Ahmed,
Great job with the boilerplate. We would love more stuff on Gutenberg from you.
In my opinion, instead of complaining we should all just contribute to make it better, be it coding or giving feedback after using.
It’s not like people have to use it right now. And five releases in the last 29 days shows developers are working hard to make it better.
I was a bit scared too knowing I would have to work harder on my plugins, change a lot of stuff. Then again, it comes with lots of possibilities, challenges, lessons. So, I am having an open mind now.
That’s very kind of you to say! π― Sure thing!
That’s true! A lot of developers including myself, we are doing just that! You should join us. :)
It WILL be like that once the Gutenberg editor gets merged in the core. By the end of this year I suppose. Are you ready for that?
Moreover, the mention of five releases in 29 days was to state the point that the things I talked about in this post can go stale and irrelevant when the new features and fixes are in place!
Exactly! There is a charm in working with cutting edge software. It has both pros and cons!
Thanks for dropping by, Imtiaz!
It is going to hard but not impossible, rough starts often leads to greater successes. I will give time to learn it, thank for giving beginners like me a head start.
I more of a frontend developer so i must admit i am gonna have hard time learning it
Sure, thing! Give it a go and contribute if you can find and improve something :)
No one is saying it’s going to be impossible. I think you got the wrong meaning here. ;)
Sure, go ahead! Break a leg! β Cheers!
A great post Ahmad, you are the champ!
Thanks, man! π€
Thank you Ahmad.
I’ve been doing some of my own experiments creating custom blocks for Gutenberg, but this is such a nice concise collection.
I saw `enqueue_block_editor_assets` introduced the other day, but haven’t had time to test the hook yet. So thank you for demonstrating the use of that too.
Your webpack setup is also nice and easy to understand.
Looking forward to seeing more :)
I am glad this boilerplate helped you! Make sure you star it on GitHub for the upcoming changes. And maybe subscribe to my new fortnightly newsletter.
Thank you for contribution to the WordPress community. Your work on this boiler plate is outstanding. Also, your pros and cons are insightful and helpful in understanding Gutenberg.
Glad you liked it!
That’s very kind of you to say! π―
Great write up, thanks for that Ahmad. Will study everything more.
What is not clear to me, is why the Gutenberg project means the removal of the metaboxes. Meta boxes (created in themes or plugins) are used for custom meta fields. Not post content. The WordPress editor is for editing post content. So these are two different things. So why does the Gutenberg editor mean the custom meta boxes have to be/will be removed? Why can’t they just exist both, whenever Gutenberg is implemented? I can understand a little visual change, but a complete removal, not.
I have used custom meta boxes for all kinds of postmeta fields (think about a real estate website with all kinds of postmeta fields for meta info on buildings/projects), in dozens and dozens of websites I have build for clients. They all will break if Gutenberg is released and meta boxes are removed. If that happens I can file for bankruptcy when my clients’ websites need to be fixed.
Hope it’s ok to ask here.
That’s very kind of you to say! π―
I get what you are saying, I think you should post this concern in the issue #952!
I’ve read where there were going to be metaboxes per block. That’s useful! Not.
You’re assessment about what is going to happen when metaboxes are removed or relegated to content blocks is correct. But it isn’t just metaboxes that will be “destroyed” in a sense with Gutenberg in the core, it is also pages and posts. The whole WP structure will be gone in another two years.
The problem is that people see any opposition as “complaining” “being negative” “not wanting to learn new things”, etc. Gutenberg isn’t about a change to the visual editor, it is a completely new WordPress coming, and that is worth opposing.
Got another example I created today you might consider including. It shows how to add a custom shortcode to the editor, in this particular case the Gravity Forms shortcode.
lucasstark/gutenberg-gravityforms
Great, would you be interested in sending a Pull Request?
Hi,
I try to develop a page builder on top of Gutenberg. I’m trying to make pre-made content.
*For that purpose, I will create block that can use external image/video.
My question:
Is it possible making pre-made content like in page builder?:
-We save our created content as XML.
-Then we put the XML in our plugin/theme.
-Then we create one block for each saved XML complete with image of the content.
-When click the pre-made content button, pre-made content populated.
(Using Gutenberg, this question looks like general WordPress question. I tried to find documentation & example but it seems to be too few talking about this.)
Thanks a lot
Thanks for such an informative article on Gutenberg.
Awais, please recommend, which Javascript library should start learning to develop Gutenberg blocks etc ?
If possible, please give the Pros and Cons of top 3 JS Libraries in context of Gutenberg.
Once again thanks for your awesome Gutenberg Boilerplate.
Hey, Anna!
Thanks for dropping by. Well, as of now, it’s not clear which JS library is going to make it in the core but chances of it being ReactJS are quite great. I’d suggest you to signup at my newsletter called WPTakeaway https://AhmadAwais.com/subscribe/ β I’ll share more advice as well as an article there about different JS frameworks!
Hey there Ahmad,
Great article. I’m still processing the large change that will come with Gutenburg, but your article has helped me unpack it a bit.
I need to look at your source, but here’s a question that your source may not answer: I read through the exchange between Facebook and Matt Mullenweg that you could essentially use any JS you wanted to build out blocks. Is that still the case, or are they sticking with React and Webpack only?
Thanks again!
Hey, Matt!
Glad you liked it! π―
I think we are not moving away from React at this stage especially after it’s MIT relicensed. And yes, Webpack is pretty great for bundling JS. I have a new project that I plan to release soon, that will help you get started with it.
Great write up. Would’ve loved to have seen Vue used for Gutenberg instead of React. With complexity being such a common topic surrounding Gutenberg, and Vue being generally considered to have a lower learning curve – seems like it would have been a good choice.
That’s very kind of you to say! π―
I see where you’re coming from to this point, but if you take this article for a read Did WordPress Just Influence Facebook to Relicense React Under MIT License β I’m sure you’ll find out the how’s and why’s of where we’re at and what I think about it.
Thank you for posting this. I’m working with Gutenberg trying to figure out how older content will migrate to Gutenberg and it has been a disaster so far. None of the content will migrate cleanly and it’s been one big headache to make it work.
About the licensing I wonder if this will change Mat’s position on dual licensed software being available in the WordPress Marketplaces for themes and plugins now that core has taken the dual licensing approach particularly after he wrote this: There is No Such Thing as a Split License
Hi
Can i write new block wihtout npm/react and just with javascript?
Hey β npm and react are JavaScript. You’ll have to learn these to be able to write good code. That’s my opinion. Learn one thing at a time and go with the flow.
Editable block is not working with development version (5.0-beta4-43896).
If you read the notice at the top of this post, it’s over an year old. β οΈGutenberg Boilerplate has been deprecated in favor of create-guten-block. Go ahead π and use create-guten-block β https://github.com/ahmadawais/create-guten-block
Thanks for sharing this tutorial. Can you also please guide me how can I create a block template? I am doing the same using this resource but itβs giving an error and I am having some programming lines in front end. This is the code
add_action( βinitβ, function() {
$args = array(
βpublicβ => true,
βlabelβ => βNewsβ,
βshow_in_restβ => true,
βtemplate_lockβ => βallβ,
βtemplateβ => array(
array( βcore/paragraphβ, array(
βplaceholderβ => βBreaking Newsβ,