I’ve been doing so much Gutenberg work over the last few weeks that I thought I would take this week to review a few of the things I’ve learned about WordPress Gutenberg so far. (I spent a bit of time working on other projects but Gutenberg related work was 67% of my week. )
It is always changing
When I first started working on Gutenberg blocks I kept looking at the Gutenberg code on GitHub until I realized that GitHub’s master branch is changing every few hours, and I was not using the very latest WordPress version on my site for development. I accidentally started trying to use code that was available in the latest Gutenberg but wasn’t yet added to the stable WordPress build I was on. I recommend cloning the Gutenberg repository to your local computer for whatever version of WordPress you are working on, that way you have a reliable codebase to work with.
The upside to Gutenberg always changing is that they are fixing bugs and making improvements every day, so something that doesn’t work right now could be fixed very soon.
Documentation is lacking
Gutenberg was released with WordPress 5.0 on December 6, 2018. It has been in development for over 2 years now and the basic documentation at https://wordpress.org/gutenberg/handbook/ is an acceptable start. I would love to see a lot more complex examples of code in the official documentation as well as tutorials and components developed by the community (yes, I know, I am part of that community). Over the next few years I expect to see a multiplication of new components, complicated examples, use cases, customizations, and tutorials that will make it much easier for new Gutenberg developers to find answers.
My best resources for finding answers have been looking at how Gutenberg core editor does things, asking around in slack channels, viewing issues on GitHub, and reading the few tutorials that covered the topics I cared about. If you have a question about Gutenberg development hit me up on twitter.
Components, components, components
As of right now there are almost 200 custom components in Gutenberg, and you can find documentation for a huge chunk of them at the official Gutenberg handbook. Anyone looking to create a new Gutenberg block or format type is going to want to utilize the existing modules that WordPress makes available.
Let’s take a quick peek at the code for the built in “Spacer” block found in Gutenberg.
/**
* External dependencies
*/
import classnames from 'classnames';
/**
* WordPress dependencies
*/
import { Fragment } from '@wordpress/element';
import { __ } from '@wordpress/i18n';
import { InspectorControls } from '@wordpress/editor';
import { BaseControl, PanelBody, ResizableBox, G, SVG, Path } from '@wordpress/components';
import { withInstanceId } from '@wordpress/compose';
Check out all those WordPress dependencies! This very simple block is using 10 dependencies coming from WordPress itself: Fragment, __, InspectorControls, BaseControl, PanelBody, ResizableBox, G, SVG, Path, and withInstanceId. Understanding what pieces WordPress has available is a key factor in efficiently developing new Gutenberg functionality. WordPress has built in components for picking colors, link inputs, toggling things on and off, collapsible panels, icons, buttons, and so much more. Lubus has graciously set up the WordPress Storybook site where anyone can go and play around with components and easily read the related documentation. It is not an exhaustive demo of all components available, but it includes the most common ones.
During development of a new block we want to utilize core WordPress components, and whenever possible, create our own common components that can be reused across multiple custom blocks. This simplifies the development of new similar blocks and makes it easy to handle improvements that can affect all the blocks using that common functionality. If your new component feels very useful and you think it could be helpful to someone else then share it on GitHub or your blog to save other Gutenberg developers from having to develop the same thing.
Wrapping up
With around a month of Gutenberg and React development under my belt, I am still only scratching the surface, but at least I have functional blocks that work for my clients’ needs.