From React to Gutenberg, a beginner’s journey

Later this year, Wordpress will introduce one of the biggest changes since it’s launch.

It’s not an overhaul of the front-end, or anything that an average website user will even see. It’s an overhaul of the website author’s publishing experience.

At the moment, that experience looks something like this:

The Wordpress editing experience right now, soon to receive a Gutenberg overhaul.

But, as of autumn 2018, it’ll look, well, a bit more like Medium. Or Squarespace, or Wix, or whatever other drag-and-drop publishing platform takes your fancy.

It will take that big, empty, familiar content editor box and turn it into a series of blocks. Blocks are intended to be simple and reusable. Developers can even create their own, as an alternative to drowning users in a sea of custom fields and meta boxes.

Given that Wordpress now runs over a quarter of the web, it’s critical to get such a foundation-shaking change right.

An example of custom two blocks built for Gutenberg, along with a standard paragraph block in the middle.

Since its inception, Wordpress has been all about PHP, for better or worse.

But that paradigm can only persist for so long. Modern web apps are increasingly Javascript driven, and Wordpress is starting to look a bit old-fashioned.

Wordpress already made one giant step toward modernity when it gained its own REST API — opening up the platform and making it possible to create an entire multi-app publishing ecosystem, with Wordpress at the centre.

Gutenberg is another step in the same direction. It is unapologetically Javascript-driven. If you want to build and extend Gutenberg blocks, you must be fluent in Javascript first.

Behind the scenes, Gutenberg is powered by React, the Javascript wonder library for building fast, modern web apps.

Now, React is notoriously tough for beginners to wrap their heads around. It requires a heck of a lot of tooling and configuration just to get up and running. Whole projects have been created to simplify this burden.

In fact, to many people, React is everything that’s wrong with modern web development. It’s unwieldy, confusing overkill.

Now, Gutenberg has tried to deal with this by providing their own, simpler API on top of React’s complexity for developers. Perhaps the pure-PHP developers that make up the bulk of the Wordpress community will feel better with that than if they were told to start learning React in order to continue customising their favourite tool?

Well, as a person who has some React experience, that extra API layer confused me at first. I struggled to relate the Gutenberg functions to what I knew from React and Javascript already.

But, two days into creating some custom blocks, it’s all starting to click. Comfortingly, you don’t need to know that much React to make Gutenberg work for you.

It’s still a massive change from the “traditional” methods of Wordpress theme and plugin development. Registering a custom widget or meta box with PHP feels very different to working with Gutenberg, and not just because of the language difference.


If you’ve written some JSX — an odd “HTML-in-javascript” language that sounds like a stupid idea until you actually try it out, you’ll pick up Gutenberg block development very quickly.

Learn JSX if you don’t already know it. You don’t need it to develop Gutenberg blocks, but without JSX, you’ll be making obscure function call after obscure function call without really understanding why. With JSX, a simple block might look like:

<p>Hello world.</p>

But without it, you’ll be faced with something like:

el( 'p', 'Hello world.' );

The latter style quickly becomes tough to read and interpret, especially with more complicated blocks.


Error messages in Wordpress tend to be PHP errors printed into the markup of the page. With Gutenberg, these are all Javascript errors you’ll need to use your browser’s dev tools to inspect, even with the Wordpress debug mode turned on.

I ran into a lot of issues around block validation errors. Gutenberg still spits out plain old HTML markup when a post is saved. When the user clicks the “Edit Post” button, it walks the HTML, teasing out which blocks are which. This is particularly tough if the custom blocks you define have user-editable fields.

On my first go, it took me about ten tries to show Gutenberg exactly how to take its plain HTML and turn it back into a block for editing.

Resources for learning block development

Gutenberg is still in beta, and so the official Wordpress Handbook documentation for creating your own blocks is a fair place to start, but is very brief.

I found the docs in the Gutenberg Github repo infinitely more useful, especially when trying to understand how to make my blocks user-editable.

Creating your custom block involves a fair amount of PHP and JS overhead. To eliminate this overhead, I really enjoyed using create-guten-block, which creates all the boilerplate code in a single terminal command.