How To Find the Gutenberg Source Code in WordPress 5.0

WordPress 5.0 ships with the Gutenberg plugin source code integrated into Core. As a consequence there are changes to how WordPress now ships JavaScript compared to previous releases. So even experienced developers might not be immediately able to find the Gutenberg source code in WordPress 5.0.

In this post you’ll learn how to:

  • Download the source code of WordPress.
  • Download the Gutenberg JavaScript dependencies.
  • Discover the location of the most important Gutenberg JavaScript libraries.
  • Create a runnable version (build version) of the source code.

Downloading the WordPress source code

We’ll use the Git mirror hosted on Github to retrieve the source code. To do so, open a Terminal window, switch to a directory of your choice, and clone the repository to your machine with:

git clone https://github.com/WordPress/wordpress-develop
Cloning the WordPress Develop Git repository to local.
Cloning the WordPress Develop Git repository to local.

Now that we have downloaded the source code, we need to switch to the 5.0 branch. Change into the wordpress-develop directory, and type git checkout 5.0

Checking out the 5.0 branch in the WordPress Develop Git repository.
Checking out the 5.0 branch in the WordPress Develop Git repository.

Downloading the JavaScript packages

For this step, you need to have Node.js & NPM installed on your local machine. You can download an installer from the Node website that contains both tools.

One of the major changes in WordPress 5.0 is that the source code is no longer all contained in the WordPress Develop Git repository. Instead all of the JavaScript libraries that make up Gutenberg need to be downloaded from the NPM repository.

This changes WordPress from being a monolithic application to a more modular approach. In fact each package represents an independent module, that could also be used in other applications, not just WordPress.

To download these JavaScript dependencies, run npm install at the root of the wordpress-develop directory.

The WordPress Develop directory will now look like this:

wordpress-develop/
|
├── Gruntfile.js
├── composer.json
├── composer.lock
├── jsdoc.conf.json
|
├── node_modules/
|
├── package-lock.json
├── package.json
├── phpcs.xml.dist
├── phpunit.xml.dist
|
├── src/
|
├── tests/
|
├── tools/
|
├── webpack.config.js
├── wp-cli.yml
├── wp-config-sample.php
└── wp-tests-config-sample.php

Exploring the NPM setup

If you are unfamiliar with how NPM works, then this might seem like black magic to you. However, there are only a couple of things to know that will make this a lot more understandable:

  • The package.json file indicates the packages, along with their desired version numbers, that should be downloaded from NPM.
  • The devDependencies key in the package.json contains the list of packages needed for development. These are usually tools to build or lint the JavaScript.
  • The dependencies key in the package.json contains the list of packages needed for the application. Without these, the application will not work.
  • The node_modules is the directory that contains all the packages we just downloaded, along with their dependencies.
  • The package-lock.json file contains all the version numbers and hashes of all the downloaded packages.

Now that we have seen how the packages get downloaded, we’ll have a deeper look at which of them are specific to Gutenberg.

Exploring the WordPress JavaScript packages

If you look into the package.json file, you’ll see a number of package names that start with @wordpress. These are the different pieces that make up Gutenberg, as well as part of the Core JavaScript libraries.

The WordPress packages are located in node_modules/@wordpress/<package-name> at the root of the wordpress-develop directory. So if you want to browse the source code, this is where to look.

The most important packages are (sorted alphabetically):

  • block: Exposes the API to interact with blocks: registration, settings, validation, saving, etc.
  • block-library: Registers the Core blocks that ship with WordPress 5.0. If you want to know more about how blocks work, this is the place to look.
  • components: Generic React components for building user interfaces.  Examples are buttons, drop downs, date pickers, radio controls, checkboxes, etc.
  • composeHigher Order Components that add basic features like unique instance identifiers to components. 
  • core-data: Helper library to retrieve or change data in the database via the WordPress Rest API. Build upon the data package.
  • data: The data handling API, build upon Redux. Includes client side storage mechanisms to reduce the number of needed requests to the REST API endpoints.
  • date: Helper library to deal with dates in JavaScript. This is required to due the way that WordPress handles dates in PHP.
  • edit-post: The editor application itself. For internal use only.
  • editor: Components that are specific to the block editor. Examples are the rich text editable field, the alignment toolbar, the inspector (sidebar) control, etc.
  • element: An abstraction layer on top of React. You’ll use this package to create your own custom React components.
  • hooks: Translates the WordPress hook concept to JavaScript.
  • i18n: Helpers for handling translations in JavaScript.
  • plugins: Exposes the API for Gutenberg plugins. Mostly used in combination with custom sidebars that are added to the editor.
  • shortcode: Shortcode parser build in JavaScript.

Exploring the Gutenberg PHP code

Gutenberg has only a handful of PHP files. These have been integrated into the layout of the WordPress codebase, in the wp-includes directory:

  •  blocks.php contains functions for registering blocks, parsing block content, and rendering blocks on the front end.
  • The blocks directory contains the registration code and render callbacks for some of the Core blocks that require PHP to work.
  • The endpoints specific to Gutenberg have been moved to the rest-api directory.

Building WordPress 5.0

In the current state, you do not yet have a working piece of software. The missing step is building the application.

To do so, run npm run grunt build at the root of wordpress-develop. This will add a build directory with build versions of the source code.

The Gutenberg packages are written in the ES2015/ES6 JavaScript version. Additionally they partly also use language features added by React. Browsers cannot understand this code. Therefore the source code needs to be transformed into plain ES5 JavaScript.

As a consequence, there needs to be a build process. The act of transforming source code from one language into its equivalent in another language is called transpiling. There are other tasks done during the build process, but this is the most important one.

Building turns each individual WordPress JavaScript package into a single JavaScript file. These files are located in the build/wp-includes/js/dist directory.

The wp-includes/script-loader.php file contains a wp_default_packages_scripts() function which registers all these scripts in PHP. This allows the build scripts to be added as dependencies via PHP, both in Core, and for custom Gutenberg blocks in plugins and themes.

The third party JavaScript libraries used by Gutenberg are located in the build/wp-includes/js/dist/vendor directory.

Now all you need to do is create a wp-config.php file, and you’ll be able to run WordPress 5.0 out of the build directory.

Conclusion

You are now much more familiar with how modern JavaScript applications are structured, and how they are built. This will serve you well when developing your own Gutenberg blocks, as the workflow is similar.

If you’re not yet familiar with developing custom Gutenberg blocks, consider reading this guide for learning Gutenberg development in 6 days.

The Beginner’s Guide To Create Guten Block

If you feel lost among all the development setup needed to create a Gutenberg block, then this guide is for you.

We’ll look in detail at how Create Guten Block can be used to simplify Gutenberg block development. We’ll start by looking at the technical implementation of the tool. Afterwards we’ll use it to create and then customise a sample Gutenberg block.

You do not need to have any knowledge of Gutenberg development to get started. The tutorial assumes that you are on MacOS X, but it also works with minor changes on Windows and Linux.

What Is Create Guten Block?

Create Guten Block is a project generator. Its focus is on generating a WordPress plugin with all the files needed for a Gutenberg block.

This means that whenever you want to create a block, you do not need to do all of the set up yourself. Instead you run a single command, and all the source files and configuration setup is done for you.

The tool is open source, and is maintained by Ahmad Awais.

How Does Create Guten Block Work?

Create Guten Block is a command line tool. This means that you interact with the tool by entering commands into a Terminal window.

There are only a couple of simple commands you need to know. However if you feel uneasy using the command line, I recommend reading this introduction post.

From a technical standpoint, Create Guten Block is a collection of JavaScript files. To web developers, this might at first seem surprising, as the JavaScript runs as a command line application.

This is made possible by Node.js, a JavaScript run-time environment that executes JavaScript code outside of a browser. Node, and the surrounding ecosystem, is crucial for modern JavaScript development.

So Create Guten Block is a specific type of JavaScript application, that relies on tools provided by Node to be installed and executed.

On Overview of Node Tooling

The JavaScript code in Create Guten Block is bundled in packages, using the Node Package Manager, or NPM. These packages are then published to the NPM Registry.

The NPM Registry is an online collection of open-source software JavaScript packages. Developers can download these packages, and use them in their own projects.

To do so, developers can interact with this repository via the npm command line tool. As an example running npm install <package-name> will download the requested package to from the repository to your local machine.

npx is a companion to npm, focussed on command line applications and other executables. It downloads and then executes packages from the NPM Registry.

As Create Guten Block relies on Node and NPM, make sure that you have these applications downloaded and installed on your machine.

Using the Create Guten Block Command

First we need to verify whether Node and NPM are installed correctly.

Open a terminal window and type node -v. This will show the installed version of Node. It needs to be higher than version 8. Repeat the same for NPM with npm -v. The requirement here is higher than version 5.3.

Now that you are all set, we can start creating a plugin for a Gutenberg block.

Navigate to the wp-content/plugins directory of your local development install. Then run npx create-guten-block hello-world-block.

Once the command has finished running, there will be a new directory called hello-world-block in the plugins directory.

In the WordPress admin, under Plugins, you’ll see that a new plugin has been added:

The Hello World Gutenberg block plugin generated by Create Guten Block.

Activate the plugin and, add the block to a post:

A view of the block inserter, showing our newly created Hello World block.

The block has two different views for the back end and the front end.

The editor view of the Hello World block.
The editor view of the Hello World block.
The front end view of the Hello World block.
The front end view of the Hello World block.

Structure of the Gutenberg Block

This on overview of the files and directories contained in the Hello World block plugin directory:

hello-word-block
|
├── .editorconfig
├── .eslintignore
├── .eslintrc.json
├── .gitignore
|
├── dist
| ├── blocks.build.js
| ├── blocks.editor.build.css
| └── blocks.style.build.css
|
├── node_modules
|
├── package-lock.json
├── package.json
├── plugin.php
├── README.md
|
└── src
├── block
| ├── block.js
| ├── editor.scss
| └── style.scss
|
├── blocks.js
├── common.scss
└── init.php

Let’s take a look at what these files do.

Configuration files

  • .editorconfig contains configuration for the code editor that you are using. You can read more about what this file does at EditorConfig.org.
  • .eslintrc.json contains the configuration for ESLint. When in development mode, all the JavaScript files in the plugin will get checked for coding standard violations against this config.
  • The .eslintignore file contains a list of JavaScript files that ESLint should ignore.
  • .gitignore is a starting point for which files to ignore from Git source control.

Main plugin file

The plugin.php file contains the plugin headers, and bootstraps the PHP code of the block by including the src/init.php file.

The source directory

The src directory is where the source code for the block lives:

  • init.php registers the block, and enqueues its built JavaScript and CSS assets from the dist directory. We’ll look into how this build process works in the next section.
  • blocks.js is the central entry point for the build process. Therefore any JavaScript file that is not included here won’t be part of the build.
  • block/block.js contains the JavaScript source code of block.
  • common.scss is a file for sharing Sass variables between the other SCSS files in the project.
  • block/style.scss contains the block styles for both the front end and the back end.
  • block/editor.scss contains additional styles for the back end view of the block.

The distribution directory

The dist directory contains the files built from source:

  • blocks.build.js contains all the JavaScript from src/blocks.js, transpiled and minified.
  • blocks.editor.build.css contains the compiled and minified Sass from the block editor styles.
  • blocks.style.build.css contains the compiled and minified Sass from the block editor styles.

The Node files

The package.json file contains the list of NPM packages used by the project. It also registers the scripts that can be run on local via NPM.

The node_modules directory contains the source code of all the NPM packages used by the project. These files were downloaded from the NPM directory during the creation process of the plugin.

Using the development mode

Let’s modify the boilerplate code to see how Create Guten Block is used during development.

To do so, you need to switch into the hello-world-block directory, and run npm run start.

A screenshot of the Terminal with the development mode running.
A screenshot of the Terminal with the development mode running.

Modifying code

We now can go into sr/block/editor.scss and set the background property to #ff0. This is what the styles will look after the change:

.wp-block-cgb-block-hello-world-block  {
background: #ff0;
border: 0.2rem solid $black;
color: $black;
margin: 0 auto;
max-width: 740px;
padding: 2rem;
}

When you now reload the Edit Post screen of the the Hello World post we created earlier, you’ll see that the background of the block has changed.

A view of the modified Hello Word block in the editor.
A view of the modified Hello Word block in the editor.

How did this happen? When in development mode, all JavaScript and Sass files will be rebuild automatically on every change. You still need to reload the page though to see the changes.

Debugging issues

The React code generated in this mode is not optimised for production. Therefore if you run Gutenberg in development mode, you’ll be able to see error messages in the browser console when the block is broken.

An example of React errors displayed during development.
An example of React errors displayed during development.

In addition, the Terminal window in which you have run npm run start will display error messages for issues in the JavaScript code.

An example of a JavaScript error displayed during development.

Building production code

Once your block is ready, and you want to use it on a production website, you can run npm run build.

A screenshot of the Terminal after the production files have been build.
A screenshot of the Terminal after the production files have been build.

Conclusion

If you have gotten this far, then congratulations for completing the tutorial!

You now should be ready to start building your own blocks. If you have any questions or suggestions, please let me know.

If you’re not yet familiar with developing custom Gutenberg blocks, consider reading this guide for learning Gutenberg development in 6 days.

Shortcut to Gutenberg: How To Learn Gutenberg Development in 6 Days

Recently I published How To Learn Gutenberg Development, which outlines a roadmap for learning ES6, React, Redux, and Gutenberg. This is a proven, and sure way to master Gutenberg.

But this approach also takes time. In fact several readers have reached out to me expressing that they don’t have time for a long learning process. With WordPress 5.0 arriving on 27 November, developers need to be productive with Gutenberg right now.

As a consequence I’ve reworked my initial learning approach, to fit with this short timeframe. The learning process outlined below takes 6 days, or 3 weekends, or 48 hours. At the end of it, you’ll be able to:

  • Adapt existing WordPress themes to work with Gutenberg content.
  • Add Gutenberg specific features to themes.
  • Understand the basics of React.
  • Feel comfortable exploring Gutenberg’s user interface component library.
  • Develop custom Gutenberg blocks.

As this is an accelerated schedule, it’s important that you get rid of all distractions. In addition make sure that you do not exceed 8 hours of screen time per day. Once you have completed the assignment for each day, you have done all that is needed for the learning progress.

So when in doubt, err on the side of spending less time in front of the screen, and more time relaxing. Furthermore it is important that you decompress at the end of each day, and get enough sleep. Only this will ensure that you memorise what you worked through. 

And with that, let’s get started!

Day 1

Morning: Create content with Gutenberg

If you have used Gutenberg regularly for creating content in WordPress, you might skip this step. However if you’re new to Gutenberg, then this is an important starting point in the learning process.

Set up a local installation, with the Gutenberg plugin, and the Twenty Nineteen theme. Then start creating content: write a post, recreate the layout of an existing article, or play around with the available blocks.

Meanwhile do not worry about how the content displays on the front end. Keep your efforts limited to the Post Editor itself. The objective is to familiarise yourself with the user interface and editing process of the Gutenberg editor.

Afternoon: Gutenberg Theme Development course

By now you should be well acquainted with using Gutenberg. Time to dive into development.

Sign up for the Gutenberg Theme Development course. This is a paid course, but as you want to save some time, you got to spend some money.

Once you have signed up, work through the first three parts of the course:

  1. Gutenberg Compatible Themes.
  2. The Gutenberg Starter Theme.
  3. Styling Default Blocks.

As everybody learns at their own pace, you might have some extra time after working through these chapters. If so, use this additional time to practise what you just learned. That is to say make an existing theme Gutenberg-ready.

For this you can install the Block Unit Test for Gutenberg plugin. This plugin creates an overview page with all the Core blocks, including multiple variations if supported. It is therefore a great starting point for adapting a theme.

Day 2

Morning: Gutenberg Theme Development course

Continue working through the Gutenberg Theme Development course by completing the chapter on Custom Colour Palettes. This chapter should be relatively straightforward, so move through it quickly.

After that, work through part 5 of the course: Block Templates. As this is a more complex topic, make sure to take your time to work through the lessons.

Afternoon: Theme development exploration

If you haven’t completed the theme development course yet, then use the afternoon to finish it.

However if you finished the course, take the afternoon to review some of your existing client projects, and brainstorm how they could leverage Gutenberg.

Because surely there are custom implementations using metaboxes, shortcodes, page builders that could be replaced by Gutenberg blocks. Take notes on any possible solutions that you come up with, and take note of any issues you run into.

Day 3: Learning React

After the introduction to Gutenberg, it’s now time to dive into learning React.

Above all it is important that you don’t buy into the common misperception among WordPress developers that React is hard. In opposition to WordPress, React has a low barrier to entry, great documentation, and is a pleasure to work with.

The best concise introduction to React is the official Intro To React tutorial.

Keep a pen and paper ready while working through the tutorial. When something seems unclear, or unfamiliar, note it down. But do not allow yourself to get distracted from completing the tutorial.

You should be able to complete the tutorial within a day. If you finish early, and still have energy left, feel free to pass on to the assignment for the next day. If you feel tired, log off, and rest up.

Day 4: React & JavaScript practice & exploration

The day before, you got your first introduction to React. You also more than likely have written more JavaScript than you would usually during a work day. Which is great, as this hopefully has shown you how fun writing React is.

Additionally, you might have noted down a lot of concepts that were unclear to you. Therefore you should take a day to research and clarify any of these outstanding questions.

For React, it makes sense to review the main concepts again. For JavaScript, you might have encountered syntax that was unknown to you. This is likely due to the code examples using ECMAScript 6, so check out this overview article of these new language features.

If you feel like you need more practice with the basics, try and recreate the app build during the tutorial on your own. If not you can go beyond the tutorial, and build a basic to do list app. Keep it simple, and just use the component state for storage.

Day 5 & 6: Gutenberg Development Course

Days 5 and 6 will build upon all the work done previously, to introduce you to custom Gutenberg block development. The best way to do this is to sign up for work the Gutenberg Development Course. This is a paid course, but well worth the money.

In opposition to the previous days, I won’t detail the learning process here. This is because the course is well designed, and will guide you step by step.

You have two days to complete the course, which is enough that you do not need to take shortcuts. Especially towards the end of the course, the subjects covered get more and more complex. So take your time to digest the material well.

However if you finish early, go back to your previous notes about features you could refactor using Gutenberg. Choose one that seems simple to you, and try to code it.

Additionally if you liked the two paid courses, you might want to get on the pre-sale of the Advanced Gutenberg Development topics, which will be released at end of the year. 

Conclusion

While I did not follow the exact learning roadmap outlined in this course (I took a longer path), it is in essence a short version of the path towards Gutenberg that I took. I therefore consider this the best possible approach for the available time frame. 

Beyond just the skill building, my hope is that this hands on approach learning process has eased any anxiety you might have had about Gutenberg.

Let me know about your experiences with this learning approach. I’m happy about any feedback or suggestions.

How To Learn Gutenberg Development

With the WordPress 5.0 release date fast approaching, the developer community is looking for instructions on how to learn Gutenberg development.

I’ve been using Gutenberg on production projects since version 2.5.0, or April 2018. To prepare for my first Gutenberg project, I’ve used the exact steps I’ll outline below. Other colleagues at Human Made have followed a similar path, so this is a proven approach for learning to develop Gutenberg blocks.

Step 1: Creating content with Gutenberg

This step may sound obvious, but as developers, we use WordPress differently than editorial users. Much of the writing we do is not done in WordPress, and we therefore lack the necessary experience of how writers use the tool.

Designing custom editing experiences is a key part of client projects. In order to implement the best solution for an editorial problem, you need to familiarise yourself with Gutenberg’s design philosophy, both in theory, and in practice.

So start doing more of your writing with WordPress. This will give you a better feeling for the user flow of Gutenberg, and get you familiar with its user interface.

A useful tool is the Block Unit Test for Gutenberg plugin, which creates a page with all default blocks. It provides a good overview, and is a great place to start exploring from.

Make sure that you play around with each block, to see what options are available, what possible use cases there could be, etc.

Step 2: Add theme styles for the default blocks

A second step is to adapt the CSS styles of an existing WordPress theme for Gutenberg. This is a good way to get started with development tasks using existing skills. Just pick a random theme, install the Block Unit Test plugin, and get busy coding.

Gutenberg includes default styles for each block, so start with looking at these styles. Investigate how you can override or remove these default styles, and experiment with different approaches.

Gutenberg also offers a number of optional theme features. Add support for these features to the theme, and implement the necessary styling to make them fit with the theme’s design.

Additionally, look into writing an editor stylesheet for Gutenberg. Try and replicate the front end design as good as possible in the editor. This is a good opportunity to familiarise yourself with the markup and class structure of the blocks in the back end, which differs from the front end.

Zac Gordon offers a Gutenberg Theme Development Course, for those that want to dive deeper into theme related Gutenberg subjects. If you are primarily a theme developer, or struggle to figure out things in your own, this is a good investment.

Step 3: Learn ECMAScript 6

Until this point, we have only interacted with the blocks that Gutenberg offers out of the box. Now we’ll take the first step towards building our own Gutenberg blocks.

Gutenberg is written in ECMAScript 6, or ES6 for short. To add to the confusion, ECMAScript 6 is also known as ECMAScript 2015 or ES2015. All these terms designate a specification of the JavaScript language.

It’s worth spending some time on ES6 because it introduces a whole set of new language features. These make it possible to write more concise and elegant JavaScript. A lot of these features are not yet supported in browsers, requiring ES6 to be transpiled (transformed) into ES5 during a build step.

While it is possible to write Gutenberg blocks directly in ES5, I strongly recommend avoiding this. Once you get used to ES6, going back to writing JavaScript using the “old” syntax will be a pain. Plus over time, ES6 support will be implemented in all browsers, making it the default version for writing JavaScript executed on the client side.

PonyFoo has a good overview of all the syntax changes and features in ES6, as well as a series of articles detailing certain aspects. Another good source is Wes Bos’ article series on ES6. These articles should be sufficient to give you a solid base for using ES6.

If you prefer to learn via video, Wes Bos has an extensive video course called ES6 for Everyone. This course goes way beyond what you would need to be familiar with Gutenberg.

ES6 for Everyone banner.

But depending on how you learn, it’s worth the investment, as it guides you through the learning process. This makes for a less steep learning curve compared to reading loosely related articles, and figuring out your own exercises.

Step 4: Learn React

Gutenberg is build with React, a JavaScript library for building user interfaces. React is part of several third party JavaScript libraries used by Gutenberg.

To make things more complicated, Gutenberg adds its own abstraction layer over React. This means that the way to interact with this library is slightly different in Gutenberg blocks compared to plain React projects. But React knowledge makes Gutenberg’s code base a lot less opaque.

There is a certain logic to writing React components, and a number of recurring patterns in React code. Being familiar with these before adding the particulars of Gutenberg will make the learning curve less steep.

The best way to learn React is Wes Bos’ React for Beginners video course. It will guide you step by step through building a React project from scratch, and will give you the necessary programming experience to feel at ease.

React for Beginners banner.

A viable alternative is the beginner tutorial in the React documentation. Even if you do the video course mentioned above, you will need to consult the React documentation frequently, so make sure to bookmark the link.

Step 5: Learn Redux

Redux is the client side data handling layer used by Gutenberg. Again, as with React, Gutenberg adds its own abstraction layer on top.

At this point, learning Redux is not required. You will not need to use it until you start developing more complex Gutenberg blocks. However I consider that Redux is such an ingrained part of the React ecosystem, that it’s worth being familiar with its concept.

Redux course illustration.

There is a free Redux course available on Egghead. The course is taught by Dan Abramov, creator of Redux, so you’ll be learning from the master himself.

The course is only of value of you follow along with what Dan types. This way you’ll be writing your own implementation of Redux, and you’ll discover that in its most basic form, it’s far from being black magic.

Step 6: Learn Gutenberg development basics

With all this knowledge, you’ll be now more than ready to dive into Gutenberg itself. The best way to do this is to complete the Gutenberg Development Course by Zac Gordon.

Gutenberg Development Course badge.

This course will teach you everything you need to know to get started developing your own Gutenberg blocks.

The course covers:

  • The architecture of Gutenberg: Covers the file structure, the React and Redux abstraction layers, as well as important helper libraries.
  • Introduction to blocks: The basic architecture of a Gutenberg block, as well as how it handles its style and script dependencies.
  • Registering blocks: The starting point for creating custom blocks. Covers how attributes are saved (user data added to the block), as well as the edit and front end views.
  • Example block: Practical exercises for building blocks. Includes a development boilerplate, enabling you start writing code right away. Along the way you’ll learn to implement different user interface elements (block form fields, toolbars, and sidebars), and different types of blocks (JS rendered and PHP rendered).

The course website includes a section with sample videos, so that you can get an idea of the quality of the videos included in the course.

Zac is currently working on a follow up course covering Advanced Gutenberg Development topics, which will be released at end of the year. So if you liked the introductory course, it might be a good idea to sign up for this.

Step 7: Practice

No tutorial or course can replace the experience gathered during real world development tasks. If you have followed the roadmap outlined in this post, you are well prepared for using Gutenberg in client or personal projects.

You will run into issues when exploring Gutenberg’s possibilities. But the structure of the learning process is set up in a way that you are well equipped to handle these temporary roadblocks.

You are now proficient at JavaScript, and accustomed to writing React code. This allows you to explore and understand Gutenberg’s code base. And possibly even contribute back to the project.

A List of all Default Gutenberg Blocks in WordPress 5.0

This page lists all default Gutenberg blocks that will ship with WordPress 5.0.

The blocks are organised by their category, and are accompanied by a screenshot of their icons in the block selector.

The block slug is listed for each block. Gutenberg uses this slug as a unique identifier for each block.

Common blocks

  • core/paragraph
  • core/image
  • core/heading
  • core/gallery
  • core/list
  • core/quote
  • core/audio
  • core/cover
  • core/file
  • core/video

Formatting

  • core/preformatted
  • core/code
  • core/freeform: Classic Edit
  • core/html: Custom HTML
  • core/pullquote
  • core/table
  • core/verse

Layout

  • core/button
  • core/columns
  • core/media-text
  • core/more
  • core/nextpage: Page break
  • core/separator
  • core/spacer

Widgets

  • core/shortcode
  • core/archives
  • core/categories
  • core/latest-comments
  • core/latest-posts

Embeds

  • core/embed
  • core-embed/twitter
  • core-embed/youtube
  • core-embed/facebook
  • core-embed/instagram
  • core-embed/wordpress
  • core-embed/soundcloud
  • core-embed/spotify
  • core-embed/flickr
  • core-embed/vimeo
  • core-embed/animoto
  • core-embed/cloudup
  • core-embed/collegehumor
  • core-embed/dailymotion
  • core-embed/funnyordie
  • core-embed/hulu
  • core-embed/imgur
  • core-embed/issuu
  • core-embed/kickstarter
  • core-embed/meetup-com
  • core-embed/mixcloud
  • core-embed/photobucket
  • core-embed/polldaddy
  • core-embed/reddit
  • core-embed/reverbnation
  • core-embed/screencast
  • core-embed/scribd
  • core-embed/slideshare
  • core-embed/smugmug
  • core-embed/speaker
  • core-embed/ted
  • core-embed/tumblr
  • core-embed/videopress
  • core-embed/wordpress-tv

How To Fix the “this.activateMode is not a function” Error in Gutenberg

Imagine you are busy developing a Gutenberg block. You reload the page, and suddenly the editor will break, displaying an The editor has encountered an unexpected error. message. You look into the JavaScript console of your browser, and see a this.activateMode is not a function error. 

What is the error cause?

On the screenshot above, you can see that the stack trace includes references to /wp-includes/js/media-views.min.js. Searching for the this.activeMode string inside of WordPress’ media code, we find this occurrence:

_createModes: function() {
   // Store active "modes" that the frame is in. Unrelated to region modes.
this.activeModes = new Backbone.Collection();
   this.activeModes.on( 'add remove reset', _.bind( this.triggerModeEvents, this ) );

   _.each( this.options.mode, function( mode ) {
      this.activateMode( mode );
   }, this );
},

The _ in this snippet is the entry point of Underscore.js, a helper library that ships with WordPress.

However looking further into the error message above, it contains two functions names: forEach and arrayEach.

Searching through the codebase, we find that these functions are part of Lodash, a helper library used by Gutenberg.

function forEach(collection, iteratee) {
  var func = isArray(collection) ? arrayEach : baseEach;
  return func(collection, getIteratee(iteratee, 3));
}
function arrayEach(array, iteratee) {
  var index = -1,
      length = array == null ? 0 : array.length;
  while (++index < length) {
    if (iteratee(array[index], index, array) === false) {
        break;
    }
  }
  return array;
}

Both Underscores and Lodash use _ to expose their API. When Gutenberg is loaded, Lodash overwrites the _ global variable used by Underscore. 

The two libraries include a _.each() function. But the signature is different, as Lodash’s implementation does not support the content argument:

  • Underscore: _.each(obj, iteratee, context)
  • Lodash: _.each(collection, iteratee)

This means that in this snippet from WordPress media code, the this variable is not passed along, which leads to a fatal error:

_.each( this.options.mode, function( mode ) {
      this.activateMode( mode );
   }, this );

How to fix the error?

When you are using Webpack and Babel to build the JavaScript in your Gutenberg blocks you need to  add babel-plugin-lodash as an NPM dependency. Then add an entry to your project’s  .babelrc as described in the plugin’s documentation.

This will modify the way that Lodash dependencies are included. _.each() would be transformed to _each(), therefore avoiding overwriting any of WordPress’ JavaScript globals.

If you are not using a build pipeline, and are writing your blocks in plain JavaScript, make sure to enable the no conflict mode of Lodash when enqueuing the script:

wp_enqueue_script( 'lodash', '...' );
wp_add_inline_script( 'lodash', 'window.lodash = _.noConflict();', 'after' );

Alternatively, you can also use the version packaged with Gutenberg itself, as it is enqueued in no conflict mode.

Conclusion

This guide should have helped you resolve the issue of Gutenberg breaking.

If you’re not yet familiar with developing custom Gutenberg blocks, consider reading this guide for learning Gutenberg development in 6 days.

Enabling React Development Mode in Gutenberg

The React development mode provides useful warnings and errors. It’s therefore useful when developing Gutenberg blocks.

However Gutenberg loads the minified production build of React by default, as it it offers better performance.

WordPress 5.0 Update

WordPress 5.0 contains a regression that does not allow React to be loaded in development mode, as described in this article, see Trac Ticket #45535. As a work around, you can download this code snippet, and enable it as a MU Plugin, or place it somewhere else in your custom code.

Enabling Script Debug

To use the React development mode in Gutenberg, you need to set the SCRIPT_DEBUG constant in your wp-config.php file to true.

define( 'SCRIPT_DEBUG', true );

As a result, Gutenberg will load the development version of React, and all other third party script dependencies.

Verifying the React Build

To verify which version of React is running, you can use the React Developer Tools for Chrome. It adds an icon to the browser that changes depending on which React version is running.

If you are on a website using the React production build, the icon will have dark background:

React DevTools icon on a website with production version of React.

However of the development build of React is loaded, the icon will have an orange background:

React DevTools icon on a website with production version of React

You are now ready to start developing your own Gutenberg blocks. If you’re not yet familiar with developing custom Gutenberg blocks, consider reading this guide for learning Gutenberg development in 6 days.

Third Party JavaScript Libraries Used in Gutenberg

Gutenberg is built using a number of open source JavaScript libraries.

React

The first and most important Gutenberg dependency is React, a library building user interfaces. Facebook leads and oversees the development of React as part of its open source initiative.

React itself does not make any assumptions about what the rest of the application is build on. As a consequence, React apps can run in the browser and on the server. You can even power mobile apps with React.

React DOM

ReactDOM is the React library to interact with the Document Object Model, or DOM. The DOM is the programming interface for HTML and XML documents. ReactDOM renders interfaces built in React inside of the browser.

Moment.js

Moment.js is a library for handling dates and times in JavaScript.

Lodash

Lodash is a helper library that makes it easier to interact arrays, numbers, objects, strings, etc. in JavaScript