A Quick Developer’s Guide to the WordPress Block Editor

TL;DR: You can skip all the exposition below and click here to get to the good part.

If you’re anything like me, you’re interested in the ever-changing landscape of web development, but your day-to-day work precludes you from digging too deeply into a topic during working hours unless a project necessitates it. As such, most of your study time happens during nights and weekends, either via focused study, exploratory projects, or a combination of the two. You might also happen to be interested in a lot of different topics, so the investment of digging into and not only acquiring but also retaining that knowledge is significant.

In the past year, I’ve spent some portion of time learning (or re-learning) the basics of Swift, Craft CMS, Laravel, React, Symfony Components (Console, Process, etc.), Bash, MySQL, NPM, converting XML to JSON… the list goes on and on. In some cases, I have a working app; in others, an unfinished idea. In most cases, though, my trials are loose collections of notes and throwaway code to try and understand various concepts, or to play around with a reusable approach to solving a problem even while I’m trying to understand the concepts behind the solution.

The WordPress Block Editor, released into core with version 5.0 in December of last year, has been one such challenge. I defined learning how to create custom blocks as a goal of mine in 2019, and tinkered with some reusable approaches to it early in the year. Still, most of my work this year has been related to developing back-end solutions, be they custom migrations, supporting existing architectures, or establishing approaches to object-oriented plugin development. My evenings and weekends had left time for tinkering, but most often, I was either preparing or rehearsing a presentation, spending time with friends and family, or just trying to unwind from a challenging day’s work.

To that latter point, this summer, I started working as a lead on a big project at WDS that fully incorporates the block editor into a publishing workflow. In the long term, this means I’ll have far more opportunities to work with the block editor, but shorter-term, it has meant integrating work that already exists and, as a project lead, doing more planning and strategy than actual development.

But I digress…

During the first weekend in November, I attended WordCamp US in St. Louis, MO. I sat in on some beginner sessions and workshops about the block editor to refresh and verify the knowledge I already have, and I chatted at length with one of my colleagues about his interest in JavaScript development and in the block editor in particular. It was a fun and exciting trip, capped off via a two-day summit with my client and their agency partners about our plans for the next six months.

Upon returning from St. Louis, I had a nice, long 6-day weekend in which to relax, refresh, and start digging into the block editor in earnest. My “quick start” guide follows.

What You Should Know About the Block Editor

Over the weekend, I watched Zac Gordon‘s excellent Gutenberg Block Development Course, and it helped to clear up a lot of questions that I had as a PHP developer who is trying to better understand the JavaScript ecosystem and how to work with the block editor.

Above all else, there are two primary resources for getting started with creating custom blocks in WordPress: the Block Editor Handbook and the Gutenberg plugin repository. Both of those links have just about everything you could possibly want to know about creating blocks, but they serve better as reference materials than tutorials, and that, really, is the rationale behind this post.

Here are some key takeaways I’ve learned over the weekend that will hopefully help you on your journey in developing custom blocks in WordPress, particularly if you’re familiar with a more traditional PHP-based workflow:

• The block editor is composed of a series of NPM packages. These packages correspond with what you’ll find in the packages directory of the Gutenberg plugin. This is one of the most important things to understand, particularly if you find it more helpful to look at code than README docs.
• One of those packages is the block-library, which contains all of the editor blocks that are part of WordPress core. The Gutenberg plugin here is useful, because this gives you tangible examples for how each block is constructed. As a developer new to the block editor, you can use any of these examples as a starting point for your own custom block exploration.
• The dependencies you define when you register a block correspond with other packages in the Gutenberg plugin, such as element (WordPress’s abstraction layer around React), editor (which includes components like RichText for input and BlockControls for concepts like alignment), and data (which serves as a sort of communication hub between the component and WordPress itself), among others.
• Blocks can be registered via PHP or JavaScript, but most-typically, only dynamic blocks will be registered via PHP. PHP’s role in block registration is primarily limited to making WordPress aware of the main JavaScript and CSS files required to render and make a block functional.

None of this information above will walk you through creating your first blocks (unlike the tutorials in the Block Editor Handbook, which I think are fairly sufficient for early exploration), but I do feel strongly that these details will help new developers better understand how to use the various components available from within the block editor, and more importantly, which ones to set as a dependency of a block.

For instance, the Block Editor tutorial indicates that you can require the wp-editor package as a dependency for your block and use the RichText component from it to provide a rich text input. But, it falls just short of linking back to the Gutenberg repository to provide examples and further documentation for that particular component so that developers can fully understand what it is and how it ties in with the block they’re trying to create.

Hopefully, putting together some pieces of this puzzle will help you on your block editor journey. It’s been an important weekend for discovery for me. This type of exploration can only happen during trial and error, which is why a long weekend is ideal. In my situation, the ability to apply these learnings to client work is going to go a long way toward helping me understand how things are constructed, and I’m hopeful those of you reading this will be able to apply some of those takeaways as well.