Skip to content

WordPress Gutenberg Custom Block Build Environment

What is Gutenberg

Ever since the first version, WordPress has had one editor field to rule them all. Developers have since hacked and pushed in more functionality with plugins and leveraging short-codes in increasingly creative ways.

Finally, WordPress is aiming to offer a more stable, more programmatic and standardized solution. Gutenberg is currently still in development and is offered as a plugin, but will make its way into core in WordPress 5.0. No longer are developers and editors limited to just one content block and hundreds of short-codes to manage the layout of their content. Developers can now build custom blocks with any kind of layout needed, and editors will be able to enter the content and range the blocks freely right in the editor.

Getting started

Currently, in WordPress 4.9.8, you’ll need to install the Gutenberg plugin. By the time WordPress 5 is released, this will no longer be a requirement. Gutenberg comes with a nice standard set of blocks. However, if you’re used to the layouts offered in something like WPBakery, you’ll be pretty disappointed. This is why WordPress put so much effort into creating API’s and global objects for developers to make custom blocks.

Whether you’re creating just one custom block or a full suite of them, you’ll be able to install them all using a plugin. There are already some developers creating nice NPM packages that spin up a local development build process. The create-guten-block is one of the more popular ones right now. It really does a nice job at getting a build process up and running with no fuss.

If you’re more interested in a boilerplate option, so you can pull it apart and figure out how it’s working, you can take a look at the WordPress Gutenberg Custom Blocks Boilerplate GitHub repo that I created. Before we get started with the boilerplate, we’ll need to install it into a local install of WordPress. Download the repo and just treat it like a regular plugin, move its contents to your plugin directory. /wp-content/plugins/wp-blocks-boilerplate

Turn on the Custom Blocks



Gutenberg Starter Theme

I’ve included a custom block in this repo. To get it working, you’ll need to copy this repo to your plugins directory in your WordPress install /wp-content/plugins/wp-blocks-boilerplate. After you’ve done that, you can turn it on in the WordPress admin and activate “JoshBlocks”.

JoshBlocks should work on any WordPress site that’s also running the Gutenberg Plugin (note requirements above). There are features that only work on a theme that fully utilize the new Gutenberg plugin. As such, I recommend using the Gutenberg Starter Theme. There are other themes that utilize Gutenberg, but this one is nice and clean and easy to experiment with. Also, I think it helps that it’s created and maintained by the people at WordPress.

Get local development build up and running:

  1. Within wp-blocks-boilerplate root, run npm install. This will get all the packages needed to run a basic build environment.
  2. Run the command npm run dev. This will get the dev process running. It will get webpack running and watching the development files for changes.
  3. The /assets directory is where all the compiled files are placed, so don’t try and edit stuff there. 🙂
  4. You’ll mostly be concerned with editing and creating files in /blocks. As you make new blocks, this is where you will put them. The example block is called picture-block.
  5. After you’re done editing, run npm run build. This will compile a compressed version of the plugin for you. To have a look at these commands in more depth, start by checking out the package.json scripts commands.

Get started making new blocks:

  1. It might be easier to start messing around with the sample block to see how it works /blocks/picture-block.
  2. As you edit files in /blocks/picture-block you’ll see the scripts running and showing errors if there are any. You can edit and reload your WordPress install to see what it does. It’s probably best to explore on a local install, otherwise, it’ll get old pretty quick if you have to upload and sync to a server for every little change.
  3. If you start to feel comfortable with how it works, a good next step would be to copy the picture-block directly and rename it. There are a few places to notice where you’ll have to add this new block name.
    • /blocks/index.js
    • /blocks/picture-block/index.js Note lines 37 and 39

A good start

This is only a start, setting up the development environment alone can take a long time to figure out. To really get into custom blocks and how React interacts with Gutenberg’s API you’re going to need to dig in deep. Here are a few resources I found really helpful.

  1. WordPress Gutenberg Handbook – Writing Your First Block Type
  2. WordPress Gutenberg Handbook – Block API
  3. CSS Tricks – Learning Gutenberg
  4. Gutenberg Block Development Course

Join the Culture Foundry Community

Even if you’re not ready to make the leap yet, you’ll find our community to be a helpful source of key insights and advice to help you learn more about how to thrive in digital. All are welcome.

Join the Community