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.

From a technical standpoint, Create Guten Block is a collection of JavaScript files. To web developers, this might at first seem surprising, as the JavaScript runs as a command line application.

This is made possible by Node.js, a JavaScript run-time environment that executes JavaScript code outside of a browser. Node, and the surrounding ecosystem, is crucial for modern JavaScript development.

So Create Guten Block is a specific type of JavaScript application, that relies on tools provided by Node to be installed and executed.

On Overview of Node Tooling

The JavaScript code in Create Guten Block is bundled in packages, using the Node Package Manager, or NPM. These packages are then published to the NPM Registry.

The NPM Registry is an online collection of open-source software JavaScript packages. Developers can download these packages, and use them in their own projects.

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:

The Hello World Gutenberg block plugin generated by Create Guten Block.

Activate the plugin and, add the block to a post:

A view of the block inserter, showing our newly created Hello World block.

The block has two different views for the back end and the front end.

The editor view of the Hello World block.
The editor view of the Hello World block.
The front end view of the Hello World block.
The front end view of the Hello World block.

Structure of the Gutenberg Block

This on overview of the files and directories contained in the Hello World block plugin directory:

hello-word-block
|
├── .editorconfig
├── .eslintignore
├── .eslintrc.json
├── .gitignore
|
├── dist
| ├── blocks.build.js
| ├── blocks.editor.build.css
| └── blocks.style.build.css
|
├── node_modules
|
├── package-lock.json
├── package.json
├── plugin.php
├── README.md
|
└── src
├── block
| ├── block.js
| ├── editor.scss
| └── style.scss
|
├── blocks.js
├── common.scss
└── init.php

Let’s take a look at what these files do.

Configuration files

  • .editorconfig contains configuration for the code editor that you are using. You can read more about what this file does at EditorConfig.org.
  • .eslintrc.json contains the configuration for ESLint. When in development mode, all the JavaScript files in the plugin will get checked for coding standard violations against this config.
  • The .eslintignore file contains a list of JavaScript files that ESLint should ignore.
  • .gitignore is a starting point for which files to ignore from Git source control.

Main plugin file

The plugin.php file contains the plugin headers, and bootstraps the PHP code of the block by including the src/init.php file.

The source directory

The src directory is where the source code for the block lives:

  • init.php registers the block, and enqueues its built JavaScript and CSS assets from the dist directory. We’ll look into how this build process works in the next section.
  • blocks.js is the central entry point for the build process. Therefore any JavaScript file that is not included here won’t be part of the build.
  • block/block.js contains the JavaScript source code of block.
  • common.scss is a file for sharing Sass variables between the other SCSS files in the project.
  • block/style.scss contains the block styles for both the front end and the back end.
  • block/editor.scss contains additional styles for the back end view of the block.

The distribution directory

The dist directory contains the files built from source:

  • blocks.build.js contains all the JavaScript from src/blocks.js, transpiled and minified.
  • blocks.editor.build.css contains the compiled and minified Sass from the block editor styles.
  • blocks.style.build.css contains the compiled and minified Sass from the block editor styles.

The Node files

The 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.

The 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.

A screenshot of the Terminal with the development mode running.
A screenshot of the Terminal with the development mode running.

Modifying code

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:

.wp-block-cgb-block-hello-world-block  {
background: #ff0;
border: 0.2rem solid $black;
color: $black;
margin: 0 auto;
max-width: 740px;
padding: 2rem;
}

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.

A view of the modified Hello Word block in the editor.
A view of the modified Hello Word block in the editor.

How did this happen? When in development mode, all JavaScript and Sass files will be rebuild automatically on every change. You still need to reload the page though to see the changes.

Debugging issues

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.

An example of React errors displayed during development.
An example of React errors displayed during development.

In addition, the Terminal window in which you have run npm run start will display error messages for issues in the JavaScript code.

An example of a JavaScript error displayed during development.

Building production code

Once your block is ready, and you want to use it on a production website, you can run npm run build.

A screenshot of the Terminal after the production files have been build.
A screenshot of the Terminal after the production files have been build.

Conclusion

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 looking to learn Gutenberg development, check out my posts on learning Gutenberg development in 6 days, or the in-depth Gutenberg development learning guide.