Project Gutenberg – Technology decisions

Gutenberg, the new and modular editing experience for WordPress, has been in rapid development throughout the past year and will soon arrive to our WordPress installations. Gutenberg will be released along with WordPress 5.0 (which is the next major release), and although no official date has been set for that, it’s safe to assume that it’s not very far away especially judging by the remaining features for MVP completion.

Gutenberg’s API and design patterns are at a stable enough stage where the time is ideal to discuss about the many technology decisions every WordPress developer will soon have to make, and perhaps pose some open questions up for debate.

PHP vs JavaScript

While WordPress is and will remain a PHP project, it goes without saying that JavaScript is going to have an equally important role when it comes to developing themes or plugins. Every “optimist” that hopes in relying on the Classic Editor compatibility plugin (and carrying on with business as usual) will eventually have to face the music; JavaScript is here to stay and it’ll be an extremely vital piece of the WordPress development puzzle. And it’s not like this came out of the blue:

Learn JavaScript, deeply […] take Every Opportunity to really beef up your JavaScript Chops

— Mall Mullenweg, The State of Word, Dec 2015

JavaScript is not the language you grew up with

A lot of negative things can be (and have been) said about JavaScript, and most of them would be fair, but it’s made some important strides in the last few years.

After its biggest update with the ES2015 version (a.k.a ES6), year after year new features are being added making the language more powerful, user friendly, and trustworthy.

Although Gutenberg will of course be “compatible” with the older JavaScript ES5 specification (as in, you’ll be able to develop blocks using just ES5 and no compile steps), it remains to be seen if it’s indeed pragmatic to approach Gutenberg development using older paradigms or no compilation steps.

The modern WordPress developer will have to keep an eye for JavaScript’s older quirks but also master its newly found powers, and while one would assume it would be enough, JavaScript comes with a huge and vibrant ecosystem of idioms, patterns, libraries, and tooling. Gutenberg, as with any modern JS application, has fully embraced a large part of it.

To sum it up, in my personal opinion, being fully ready for advanced Gutenberg development means:

1. Being comfortable with ESNext – referring to ES2015/16/17 and all future ECMAScript proposals (i.e. JavaScript versions).
2. Being well versed in idiomatic JavaScript, event based and async patterns, a bit of functional programming, etc.
3. React knowledge and most importantly the concepts and paradigms it introduces.
4. Redux knowledge and most importantly the concepts and paradigms it introduces.
5. Comfort with JavaScript Tooling, Babel, webpack, ESLint, Jest, etc.
6. Expert knowledge with the actual Gutenberg API.

All the above might seem like a lot, and while it’s true that the Gutenberg API provides an abstract layer over React and Redux, the key concepts the two libraries introduce are pervasive throughout it. A strong understanding of concepts such as componetization, props and state, immutability, functional and event based programming, will give anyone a significant head start.

ES5 vs ESNext+JSX

The first decision one would have to make would be whether to use the older JavaScript specification (ES5) or the newest features (ES2015 and forward).

It would make sense to ask why is it even a debate, shouldn’t we just use the most recent version? There are a couple of important caveats: The newer JavaScript specifications are not supported by older browsers (i.e… IE), and there are still features of these new standards that have not yet fully landed even in modern browsers (e.g. ES modules). To solve this issue modern JavaScript gets compiled into ES5 (a version which is universally supported in its entirety) by introducing a build step to our development process (more on that later).

If you’ve ever visited the Gutenberg Handbook, which acts as the official introduction to the project and as part of its documentation, you’ll have noticed that it offers all examples using both versions. Let’s break down the one from the above link and see how ESNext (with a build step) makes more sense.

var el = wp.element.createElement,
registerBlockType = wp.blocks.registerBlockType,
RichText = wp.blocks.RichText;

// vs

const { registerBlockType, RichText, source } = wp.blocks;

Object destructuring and the new const variable definition.

...
edit: function( props ) {
var content = props.attributes.content;
...

// vs

...
edit( { attributes, className, setAttributes } ) {
const { content, isSelected } = attributes;
...

Method definitions shorthand syntax  along with function argument object destructuring.

...
return el(
    RichText,
    {
        tagName: 'p',
        className: props.className,
        onChange: onChangeContent,
        value: content,
        isSelected: props.isSelected,
    }
);
...

// vs

...
return (
    <RichText
        tagName="p"
        className={ className }
        onChange={ onChangeContent }
        value={ content }
        isSelected={ isSelected }
    />
);
...

A build step also enables us to use a handy little feature called JSX which is what’s shown above. While you’ll see JSX mentioned as part of the ESNext spec sometimes, it is wrong. JSX is a syntax extension that React came up with and not part of the JavaScript language itself. It is reminiscent of a templating language, looks like HTML, and helps tremendously with maintaining readability in nested component structures (imagine if the first example without JSX had nested children!).

There has been a lot of debate concerning the usage of JSX when React was at its early stages. The JSX paradigm (“HTML” in JS) seemed to conflict with some puristic ideas and the general “separation of concerns” mantra which was prevalent in the front-end world. This debate has been discussed in countless articles (and still goes strong some times), so I’m not going to touch upon it. All I’m going to say is that I personally can’t fathom building React components without JSX. Use it (or not) at your own preference and coding style.

Tooling and JavaScript Fatigue

While Gutenberg puts us on rails when it comes to the higher concepts of development practices and how we’re going to structure our codebases, the build tools we’re going to use are still up to everyone’s preference. Just for bundling code we have Gulp/Browserify, webpack, Rollup, Parcel, plus a few lesser known ones. The excessive amount of libraries and the explosive growth of tooling in the recent years led to the infamous “JavaScript Fatigue” syndrome. Eric Clemmons points out in his article about JavaScript Fatigue:

Ultimately, the problem is that by choosing React (and inherently JSX), you’ve unwittingly opted into a confusing nest of build tools, boilerplate, linters, & time-sinks to deal with before you ever get to create anything.

The React community in its majority has long settled for webpack as the bundler of choice, and a lot of effort has been devoted to alleviate the pain of setting up boilerplate code. Thankfully, the Gutenberg team consists of very experienced JavaScript engineers who are very aware of this problem as well.

For that reason, the Gutenberg community has been working at creating boilerplates and scaffolds that can provide a solid starting point to being productive as fast as possible.

1. The official Gutenberg examples repo contains all versions using ESNext and a webpack configuration.
2. create-guten-block A CLI tool similar to create-react-app with bundling, linting, and testing all out of the box.
3. WP-CLI’s wp scaffold block command which scaffolds required files for a block to function.

(Note that wp scaffold block produces only ES5 code without a build step for now).

It remains to be seen how Gutenberg tooling and scaffolding will evolve over time, especially after the first release is out but the great thing is that we’re already on a great track right now and my educated guess is that we’ll soon see something official and maintained by the core team.

Learning Gutenberg

When all the boilerplate gets out of the way, the final piece of the puzzle would be to start developing actual blocks and, to achieve that, mastering Gutenberg’s API and idioms will be paramount. We all know that Gutenberg is built on top of React (and Redux) and follows many of their patterns. Its philosophy closely follows React’s component encapsulation, modularization, and general practices, along with some functional concepts and ideas from the Redux camp. I don’t see prior React expertise ever being a hard requirement in order to develop blocks, but I do feel that it’s helped me a lot and has provided a significant head-start.

Ideas like Higher Order Components, dispatching actions, state selectors, or Redux reducers are all infused within Gutenberg.

And while those ideas are prevalent, Gutenberg abstracts over all of them in a unified API and introduces new concepts in and on itself, as everything is offered as standalone modules, making it simple to use the parts necessary for each use case while limiting complexity. Gutenberg exposes its main API via important JS libraries including (but not limited to):

• @wordpress/components: Generic, reusable UI WordPress components
• @wordpress/i18n: Internationalization utilities
• @wordpress/element: Abstraction on top of React
• @wordpress/date: Date formatting and manipulation utilities
• @wordpress/blocks: Module providing utilities for registering and building blocks
• @wordpress/data: Abstraction on top of Redux
• @wordpress/editor: Module representing the WordPress Editor’s page

The Handbook is a great starting point, but it’s paramount at this point to delve deeper into Gutenberg’s API. Currently this is only possible on the GitHub repo.

Every section contains its own README document, for example the Data API is described here and the generic, reusable UI components can be found here.

From my experience, developing blocks right now is a mix and match approach of:

• Going through the handbook
• Reading the main documentation of an API (i.e. data, element, etc)
• Looking at examples on how something similar is achieved on the actual native blocks section in the GitHub repo
• Use any already existing Components from the @wordpress/components module if applicable
• Create new components out of WordPress’s primitives if necessary
• Trial & error

Should I ditch PHP then?

Of course not! PHP will always be the fundamental part of WordPress and will always have its place on the “backend”. JavaScript is going to replace most front-end templating (both client side and admin side) but PHP will still have an equally important role in actually building and architecting WordPress themes and plugins.

PHP will also work in tandem with JavaScript for creating dynamic blocks i.e. blocks that display content which might be modified without user interactions (think popular, recent, or relevant posts widgets).

A lot more to discover

Gutenberg is a journey right now, we’re all under an exploratory mood, figuring out pieces of the puzzle towards a modern publishing experience. There are definitely a lot to digest and a lot more to discover: Creating custom components and primitives, using “native” React or Redux without Gutenberg’s abstraction, making new reusable block UI frameworks for our personal theme and plugin needs, locked block templates in the place of PHP page templates, and so much more. Until the official finalized documentation and best practices emerge we’ll have to follow our engineering curiosity and fill in the blanks ourselves. It’s not going to be on a tour on the express lane, but I’m confident the end result will worth it.

How do you prepare yourself for Gutenberg? What technology choices have you made, and how are you planning on developing for WordPress after its release? Do you have any tips or tricks to share, or any questions that we might be able cover? We’d love to know in the comments section!