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 looking to learn Gutenberg development, check out my posts on learning Gutenberg development in 6 days, or the in-depth Gutenberg development learning guide.

Is there a development task that you struggle with? Do you want to know more about a particular WordPress API?

If so, please let me know by suggesting a topic for an article.