How to Create Your First Gutenberg Block with CGB
Gutenberg blocks have been rising in popularity. By now, many WordPress developers have familiarized themselves with the way Gutenberg works and are now looking to create new custom blocks for Gutenberg. So, how exactly do you create a custom Gutenberg block? In this article, we will be learning how to create your first Gutenberg block with CGB.
But what exactly is CGB? Why should you use it? Do you need to install it? So many questions! Let us get started by answering each of them.
Introducing Create Guten Block Toolkit
Before going any further, we first need to familiarize ourselves with the Create Guten Block Toolkit, or CGB as it is commonly called. Developed by Ahmad Awais, this create-guten-block is one of the many Gutenberg block generation methods out there. There are several alternatives out there and you can create Gutenberg block plugins using any method that you feel like. However, CGB is rather simple to use as there isn’t much pre-configuration that you need to worry about. Therefore, it’s a good idea for newer developers to consider taking a look at CGB for block development to get started.
Developing Gutenberg blocks can be a complicated process at first. Getting your local development environment setup to work with React, JSX, webpack, etc. can be quite the hurdle. CGB installs and configures all of this for you so you can hit the ground running and develop some blocks. We used CGB to get started developing our Atomic Blocks plugin, and continue to use it to develop new blocks!
So what does it mean that there is no configuration to worry about and how is this helpful for you?
You can update the CGB toolkit without being worried about breaking something in your code. Since there is zero configuration of its own, CGB can be updated without making changes to your code. This is what makes CGB easy to use and slightly different from other boilerplates or starting toolkits. Beyond that, you also have the standard set of features that you would expect from any decent toolkit meant for WordPress developers. CGB is versioned, updatable (as mentioned earlier) and comes with just one cgb-scripts dependency.
Major Features
The ultimate selling point of CGB is its simplicity and ease of use. Consider the following:
- Support for React, JSX and ES6
- One simple dependency
- Auto-prefixed CSS
- Works straight out of the box and does not require you to include a million other files in your project.
The cgb-scripts package handles all the other types of configuration that you might need. In other words, you do not have to include multiple other packages in order to get started with block development.
Here is a nifty example of this concept from the introductory post of CGB:
Now that we’ve covered the many good things about CGB, it’s time to get things rolling. How do you build a custom block plugin using CGB?
Step One: Installing Create Guten Block Toolkit
From here on out, you’ll need to be comfortable with working with the command line tool. You can use whichever tool you are comfortable working with.
To get started, we need to choose the directory where we want to start our plugin development. Ideally, you’ll chose a folder in your wp-content/plugins folder. Once you’ve entered into your folder, you can go ahead and run the following command to start the install.
npx create-guten-block
You will need to have at least Node.js 8 and npm 5.3 so if you encounter an error, it might be time to update your Node installation.
Confused? Where did npm come from? Well, npm stands for Node Package Manager and it comes bundled with Node.js It might be a good idea to learn about Node.js and install it (npm gets installed automatically when you setup Node). The official website has a very detailed outline of what needs to be done for installation of Node and npm. Check it out here. You will encounter npm often in your Gutenberg block development, so it’s worth it to start learning it.
Step Two: Create your first Gutenberg block
Once you have the CGB toolkit installed, you can get started with block creation and development. Here is a sample command that creates a block:
create-guten-block my-fancy-block
The above command will generate a Gutenberg block in the form of a WordPress plugin. You can activate this new block just like you would a normal WordPress plugin. Note that, however, this implies you must run the above command inside your WordPress installation’s plugins folder, as mentioned earlier. Further, you would need to follow the nomenclature requirements for WordPress plugins — no spaces, obviously.
When you navigate to your WordPress admin plugins page, you will see your new block listed as a plugin that can be activated. The general directory structure of your first block is as follows:
package.json
README.md
---
dist
+ blocks.build.json
+ blocks.editor.build.css
+ blocks.style.build.css
---
src
+ block
+ editor.scss
+ style.scss
blocks.json
common.scss
init.php
Step Three: All done!
That’s it for basic block creation! You have successfully created your first Gutenberg block with CGB and you can now start customizing and changing your block. For your reference, here is how you can get started working with your new block:
cd block-namewill navigate you to your new block’s folder. For example,cd my-fancy-blockis what you will use to get to the above-created block’s folder.npm startwill run your block for development whereasnpm run buildwill run it for production build.
Need more details such as how to update CGB and the blocks you created? Check out the often-updated official documentation of CGB.
Doing more with your first Gutenberg block with CGB
So, you have just created your first Gutenberg block with CGB. At this point, you might already have gone through the Gutenberg handbook as well as the CGB documentation. You also have a working idea of how to get things started now and how a Gutenberg block is supposed to be structured.
Let us revisit the block folder layout that we mentioned above.
package.json
README.md
---
dist
+ blocks.build.json
+ blocks.editor.build.css
+ blocks.style.build.css
---
src
+ block
+ editor.scss
+ style.scss
blocks.json
common.scss
init.php
The plugin.php file just contains a list of declarations and comments to register your block as a plugin. It alerts WordPress about the existence of a new plugin. In theory, you would not need to edit this file.
Similarly, you will not need to modify any of the files found in the dist sub-folder either. This directory contains the JavaScript and stylesheets that were compiled during your block development. The code found in the dist folder will be compressed and mostly unreadable.
When editing your block, you will be working in the src folder. This is where the original block files and styles that you edit will be found.
Notice the init.php file? This is where any PHP code associated with your Gutenberg block plugin will go to. Note that the plugin.php file will require this src/init.php to work with, so if you have any PHP code for your block, be sure to include it here.
You will also notice a blocks.js file in the src folder. This file acts as the ultimate “index” for your block, similar to a table of contents in a book. If you have any JavaScript files that your block needs, or any blocks that are to be imported, all of that should be mentioned in the blocks.js file. This file will also be compiled when saving your block.
And what about the sub-directory named block? In most cases, it will have three files within it:
block/block.jswill contain all the JavaScript needed for your block.block/editor.scsswill have Sass stylesheets for the Gutenberg backend editor.block/style.scsswill have Sass stylesheets meant for the frontend display.
Wrapping up
So there you have it! If you followed along closely, you should have created your first Gutenberg block with CGB. Furthermore, you also have a basic idea about how things work in blocks created by CGB, and what the directory structure is.
At this point, you are ready to setup your first Gutenberg block with CGB and then explore it even further. Considering the fact that Gutenberg is constantly under development, be sure to refer to the documentation and literature as often as possible to stay updated about Gutenberg and CGB.
