If you feel lost among all the development setup needed to create a Gutenberg block, then this guide is for you.
We’ll look in detail at how Create Guten Block can be used to simplify Gutenberg block development. We’ll start by looking at the technical implementation of the tool. Afterwards we’ll use it to create and then customise a sample Gutenberg block.
You do not need to have any knowledge of Gutenberg development to get started. The tutorial assumes that you are on MacOS X, but it also works with minor changes on Windows and Linux.
What Is Create Guten Block?
Create Guten Block is a project generator. Its focus is on generating a WordPress plugin with all the files needed for a Gutenberg block.
This means that whenever you want to create a block, you do not need to do all of the set up yourself. Instead you run a single command, and all the source files and configuration setup is done for you.
The tool is open source, and is maintained by Ahmad Awais.
How Does Create Guten Block Work?
Create Guten Block is a command line tool. This means that you interact with the tool by entering commands into a Terminal window.
There are only a couple of simple commands you need to know. However if you feel uneasy using the command line, I recommend reading this introduction post.
On Overview of Node Tooling
To do so, developers can interact with this repository via the
npm command line tool. As an example running
npm install <package-name> will download the requested package to from the repository to your local machine.
npx is a companion to
npm, focussed on command line applications and other executables. It downloads and then executes packages from the NPM Registry.
As Create Guten Block relies on Node and NPM, make sure that you have these applications downloaded and installed on your machine.
Using the Create Guten Block Command
First we need to verify whether Node and NPM are installed correctly.
Open a terminal window and type
node -v. This will show the installed version of Node. It needs to be higher than version 8. Repeat the same for NPM with
npm -v. The requirement here is higher than version 5.3.
Now that you are all set, we can start creating a plugin for a Gutenberg block.
Navigate to the
wp-content/plugins directory of your local development install. Then run
npx create-guten-block hello-world-block.
Once the command has finished running, there will be a new directory called
hello-world-block in the plugins directory.
In the WordPress admin, under Plugins, you’ll see that a new plugin has been added:
Activate the plugin and, add the block to a post:
The block has two different views for the back end and the front end.
Structure of the Gutenberg Block
This on overview of the files and directories contained in the Hello World block plugin directory:
| ├── blocks.build.js
| ├── blocks.editor.build.css
| └── blocks.style.build.css
| ├── block.js
| ├── editor.scss
| └── style.scss
Let’s take a look at what these files do.
.editorconfigcontains configuration for the code editor that you are using. You can read more about what this file does at EditorConfig.org.
.gitignoreis a starting point for which files to ignore from Git source control.
Main plugin file
plugin.php file contains the plugin headers, and bootstraps the PHP code of the block by including the
The source directory
src directory is where the source code for the block lives:
distdirectory. We’ll look into how this build process works in the next section.
common.scssis a file for sharing Sass variables between the other SCSS files in the project.
block/style.scsscontains the block styles for both the front end and the back end.
block/editor.scsscontains additional styles for the back end view of the block.
The distribution directory
dist directory contains the files built from source:
src/blocks.js, transpiled and minified.
blocks.editor.build.csscontains the compiled and minified Sass from the block editor styles.
blocks.style.build.csscontains the compiled and minified Sass from the block editor styles.
The Node files
package.json file contains the list of NPM packages used by the project. It also registers the scripts that can be run on local via NPM.
node_modules directory contains the source code of all the NPM packages used by the project. These files were downloaded from the NPM directory during the creation process of the plugin.
Using the development mode
Let’s modify the boilerplate code to see how Create Guten Block is used during development.
To do so, you need to switch into the
hello-world-block directory, and run
npm run start.
We now can go into
sr/block/editor.scss and set the
background property to
#ff0. This is what the styles will look after the change:
border: 0.2rem solid $black;
margin: 0 auto;
When you now reload the Edit Post screen of the the Hello World post we created earlier, you’ll see that the background of the block has changed.
The React code generated in this mode is not optimised for production. Therefore if you run Gutenberg in development mode, you’ll be able to see error messages in the browser console when the block is broken.
In addition, the Terminal window in which you have run
Building production code
Once your block is ready, and you want to use it on a production website, you can run
npm run build.
If you have gotten this far, then congratulations for completing the tutorial!
You now should be ready to start building your own blocks. If you have any questions or suggestions, please let me know.
If you’re not yet familiar with developing custom Gutenberg blocks, consider reading this guide for learning Gutenberg development in 6 days.