Title: Technical overview of Gutenberg integration
Author: Riad Benguella
Published: October 3, 2018

---

 [  ](https://profiles.wordpress.org/youknowriad/) [Riad Benguella](https://profiles.wordpress.org/youknowriad/)
12:21 am _on_ October 3, 2018     
Tags: [core-js ( 131 )](https://make.wordpress.org/core/tag/core-js/)

# Technical overview of Gutenberg integration

To better understand how we can integrate GutenbergGutenberg The Gutenberg project
is the new Editor Interface for WordPress. The editor improves the process and experience
of creating new content, making writing rich content much simpler. It uses ‘blocks’
to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/)
into WordPress, it’s crucial to know how the Gutenberg pluginPlugin A plugin is 
a piece of software containing a group of functions that can be added to a WordPress
website. They can extend functionality or add new features to your WordPress websites.
WordPress plugins are written in the PHP programming language and integrate seamlessly
with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/)
or can be cost-based plugin from a third-party. is organized.

### JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. 󠀁[https://www.javascript.com](https://www.javascript.com/)󠁿 Packages

The Gutenberg plugin is mostly a JavaScript application composed of several packages.
Each one of these packages is:

 * Generic and available as an npm package.
 * The Gutenberg Plugin registers each package as a WordPress script.
 * The Gutenberg Plugin makes the public APIAPI An API or Application Programming
   Interface is a software intermediary that allows programs to interact with each
   other and share data in limited, clearly defined ways. of each package available
   in the `wp` global variable.
 * If a package is dependent on another one, it consumes it as a global variable
   and adds it as a dependency of the WordPress registered script.
 * A package can have one or multiple CSSCSS Cascading Style Sheets. stylesheets.

**For example:**

A `@wordpress/components` npm package is registered in the plugin as a `wp-components`
WordPress script; its API is available in the `wp.components` global variable; and
depends on `@wordpress/element`.

In turn, `@wordpress/element`‘s script is `wp-element` and is consumed by `@wordpress/
components` in the bundled script as `wp.element`.

### Bootstraping the editor’s page

To display the editor’s page we call `wp.editPost.initializeEditor` from the higher-
level `wp-edit-post` package. This function takes as arguments the post to be edited
and some editor settings.

This call is made when loading the `edit.php` page localizing the required arguments
and enqueuing the `wp-edit-post` script.

### REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) 󠀁[https://developer.wordpress.org/rest-api/](https://developer.wordpress.org/rest-api/)󠁿 endpoints

Once the editor’s page rendered, all the communication with WordPress happens using
REST API calls. In addition to the regular REST API endpoints to fetch, update and
delete taxonomies, posts, etc., Gutenberg adds new REST API endpoints that include:

 * **Autosaving** endpoint.
 * **Reusable Blocks** endpoint.
 * **Root** endpoint for site settings.

Many other tweaks have been necessary in existing endpoints (taxonomies, embeds,
permalinks, post search, etc) and most of these have been merged in the previous
4.9.* releases.

### MetaBoxes

To support MetaBoxes, Gutenberg hooksHooks In WordPress theme and development, hooks
are functions that can be applied to an action or a Filter in WordPress. Actions
are functions performed when a certain event occurs in WordPress. Filters allow 
you to modify certain functions. Arguments used to hook both filters and actions
look the same. initially render the content of the MetaBoxes in a hidden DOM node
rendered using a PHPPHP The web scripting language in which WordPress is primarily
architected. WordPress requires PHP 7.4 or higher script. We also hook into the `
post.php` call to persist the MetaBoxes save call.

### Summary

So, as a high-level picture, the Gutenberg plugin is composed of:

 * JavaScript scripts and styles.
 * A PHP file to bootstrap the editor in `edit.php`.
 * REST API endpoints.
 * PHP utilities to parse, register and render blocks on the front-end.
 * PHP script to inject the MetaBoxes into the page and hooks to save the MetaBoxes.

## Integration Process

In [previous JavaScript meetings](https://make.wordpress.org/core/2018/08/28/javascript-chat-summary-august-28th/),
we discussed the packages integration approach:

Since the JavaScript scripts are built as reusable npm packages, we’ll consume them
in WordPress like any other npm package:

 * Adding a dependency in CoreCore Core is the set of software required to run WordPress.
   The Core Development Team builds WordPress.’s `package.json`.
 * Exporting the `wp.*` globals in enqueue scripts inside WordPress Core.
    - **Example:** `wp.components = require( '@wordpress/components' );`
 * Moving the script registration corresponding to each package into `wp-includes/
   script-loader.php`.

Scripts like `wp.shortcode`, `wp.a11y.speak`, `wp.utils.WordCount` can be replaced
by their corresponding npm packages. This has already been proposed for [the shortcode package](https://core.trac.wordpress.org/ticket/44987)
and should continue for other packages.

The work being done in [#core-js](https://make.wordpress.org/core/tag/core-js/) 
meetings to align the JavaScript guidelines (code style) between Gutenberg and Core
would result in a formal `@wordpress/eslint-preset` package that should be used 
as a replacement for the current JSHint config.

The REST endpoints should be moved to the regular REST endpoints location in WordPress
Core `wp-includes/rest-api/endpoints`.

The PHP utilities and classes should be moved to `wp-includes`.

Some minor tasks are also left to do in the Gutenberg repository:

 * Drop the `Gutenberg` name from all the PHP APIs still using it.
 * Finalize the `block-library` and `edit-post` packages:
    - HTMLHTML HyperText Markup Language. The semantic scripting language primarily
      used for outputting content in web browsers. BlockBlock Block is the abstract
      term used to describe units of markup that, composed together, form the content
      or layout of a webpage using the WordPress editor. The idea combines concepts
      of what in the past may have achieved with shortcodes, custom HTML, and embed
      discovery into a single consistent API and user experience. and Freeform block
      to be moved to the npm packages.
    - The creation of the `edit-post` package.

## Test Suite

**The e2e tests** are crucial to avoid regressionregression A software bug that 
breaks or degrades something that previously worked. Regressions are often treated
as critical bugs or [blockers](https://make.wordpress.org/core/2018/10/03/technical-overview-of-gutenberg-integration/?output_format=md#blocker).
Recent regressions may be given higher priorities. A "3.6 regression" would be a
bug in 3.6 that worked as intended in 3.5. when making updates to WP-Adminadmin (
and super admin). The e2e test infrastructure and the tests themselves should be
moved to WordPress Core and their stability can be considered a metric for the success
of the integration process.

Unit tests, in general, live next the code being tested. For packages, these will
stay in the Gutenberg repository and, for the files moved to Core, the tests will
follow.

## What about the Gutenberg Plugin?

After WordPress 5.0 is released, the Gutenberg plugin will continue to exist. Its
purpose will be changed to the development and the maintenance of the WordPress 
npm packages, including the editor itself, and will also serve to develop the second
phase (site customization) of the Gutenberg project. Plugin updates will continue
to be released during the 5.0 cycle.

The PHP part of the plugin won’t be needed anymore, as the plugin will just register
new versions of the scripts of the packages to replace the ones already registered
by Core.

### Share this:

 * [  Threads ](https://make.wordpress.org/core/2018/10/03/technical-overview-of-gutenberg-integration/?share=threads)
 * [  Mastodon ](https://make.wordpress.org/core/2018/10/03/technical-overview-of-gutenberg-integration/?share=mastodon)
 * [  Bluesky ](https://make.wordpress.org/core/2018/10/03/technical-overview-of-gutenberg-integration/?share=bluesky)
 * [  X ](https://make.wordpress.org/core/2018/10/03/technical-overview-of-gutenberg-integration/?share=x)
 * [  Facebook ](https://make.wordpress.org/core/2018/10/03/technical-overview-of-gutenberg-integration/?share=facebook)
 * [  LinkedIn ](https://make.wordpress.org/core/2018/10/03/technical-overview-of-gutenberg-integration/?share=linkedin)

 1.  ![](https://secure.gravatar.com/avatar/d83e6c5e7f1352050e6480e1efd50cd700448d09d661bd67a4452782424b5d2f?
     s=32&d=mm&r=g)
 2.   [davidshq](https://profiles.wordpress.org/davidshq/)  1:46 am _on_ October 3,
     2018
 3.  Very helpful overview Riad, thanks for putting this together!
 4.  ![](https://secure.gravatar.com/avatar/19347ef87f4fd5978b2184e7f05af5c780485f69dbfdefccfe3521c732a87f06?
     s=32&d=mm&r=g)
 5.   [Drew Jaynes](https://profiles.wordpress.org/drewapicture/)  4:24 am _on_ October
     3, 2018
 6.  Great writeup. It seems that the one major piece still missing is the plan for
     how documentation will be managed and maintained going forward. I’m aware there
     is currently a [Gutenberg handbook](https://wordpress.org/gutenberg/handbook/)
     already living within .org’s infrastructure, though I’m particularly interested
     in more information on how governance and continued maintenance of that documentation
     will proceed following the merge.
 7.  Corollary to maintenance of the GutenbergGutenberg The Gutenberg project is the
     new Editor Interface for WordPress. The editor improves the process and experience
     of creating new content, making writing rich content much simpler. It uses ‘blocks’
     to add richness rather than shortcodes, custom HTML etc.
      [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/)
     handbook, there is the inevitable problem of sharding the code documentation into
     multiple locations by virtue of integrating any code (particularly the PHPPHP 
     The web scripting language in which WordPress is primarily architected. WordPress
     requires PHP 7.4 or higher parts, like the REST endpoints) into coreCore Core 
     is the set of software required to run WordPress. The Core Development Team builds
     WordPress. and the docs associated with that code landing in the Code Reference.
     What, if any, are your plans for tying docs in the Code Reference back into the
     handbook, and who will be responsible for broadly maintaining that handbook?
 8.  Side note: It looks like there’s some content in the handbook that will need to
     be adjusted to present tense following the merge, stuff like “The editor will 
     endeavour” should become “The editor endeavors” etc.
 9.   * ![](https://secure.gravatar.com/avatar/4358d28c1e85f9015cb3363e024e2b238bccb44d05c4b84e9a38aafef0d83ac9?
        s=32&d=mm&r=g)
      *  [Riad Benguella](https://profiles.wordpress.org/youknowriad/)  1:49 pm _on_
        October 3, 2018
      * That’s a good question, documentation is very important for the GutenbergGutenberg
        The Gutenberg project is the new Editor Interface for WordPress. The editor
        improves the process and experience of creating new content, making writing
        rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes,
        custom HTML etc.
         [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/)
        integration.
      * As a start, we will probably continue updating the documentation in the pluginPlugin
        A plugin is a piece of software containing a group of functions that can be
        added to a WordPress website. They can extend functionality or add new features
        to your WordPress websites. WordPress plugins are written in the PHP programming
        language and integrate seamlessly with WordPress. These can be free in the 
        WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/)
        or can be cost-based plugin from a third-party. while making it clear in the
        Handbook which version you’re looking at:
      *  – Is it the integrated version into CoreCore Core is the set of software required
        to run WordPress. The Core Development Team builds WordPress. (the default)?
        –
        Is it the handbook for the updates coming to Core (The current version in the
        plugin)? – A version selector could also be integrated.
      * It’s also important to note that the setup itself is subject to change over
        time.
      * As you mentioned, the handbook needs adjustments and we’re are already improving
        its content. If you want to be involved in that feel free to take a look at
        the “docs” folder of the repository and make updates to the markdown files.
 10. ![](https://secure.gravatar.com/avatar/6f505c6be9a951929a99becb6b413dcfa583a5ca3dd0f7320766fee1481f0f82?
     s=32&d=mm&r=g)
 11.  [Jb Audras](https://profiles.wordpress.org/audrasjb/)  7:15 am _on_ October 3,
     2018
 12. Thanks [@youknowriad](https://profiles.wordpress.org/youknowriad/) for this recap!
 13. My only concerns is about updating GutenbergGutenberg The Gutenberg project is
     the new Editor Interface for WordPress. The editor improves the process and experience
     of creating new content, making writing rich content much simpler. It uses ‘blocks’
     to add richness rather than shortcodes, custom HTML etc.
      [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/)
     as a pluginPlugin A plugin is a piece of software containing a group of functions
     that can be added to a WordPress website. They can extend functionality or add
     new features to your WordPress websites. WordPress plugins are written in the 
     PHP programming language and integrate seamlessly with WordPress. These can be
     free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/)
     or can be cost-based plugin from a third-party.: in my opinion Gutenberg plugin
     should never be updated without a coreCore Core is the set of software required
     to run WordPress. The Core Development Team builds WordPress. update too. Like
     other bundled plugins, the “as a plugin” version should always follow the bundled
     version 😉
 14.  * ![](https://secure.gravatar.com/avatar/4358d28c1e85f9015cb3363e024e2b238bccb44d05c4b84e9a38aafef0d83ac9?
        s=32&d=mm&r=g)
      *  [Riad Benguella](https://profiles.wordpress.org/youknowriad/)  1:40 pm _on_
        October 3, 2018
      * The idea here is to see GutenbergGutenberg The Gutenberg project is the new
        Editor Interface for WordPress. The editor improves the process and experience
        of creating new content, making writing rich content much simpler. It uses ‘
        blocks’ to add richness rather than shortcodes, custom HTML etc.
         [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/)
        as the “development” version for the upcoming changes into CoreCore Core is
        the set of software required to run WordPress. The Core Development Team builds
        WordPress.. These changes will always make their way into Core.
      * Gutenberg PluginPlugin A plugin is a piece of software containing a group of
        functions that can be added to a WordPress website. They can extend functionality
        or add new features to your WordPress websites. WordPress plugins are written
        in the PHP programming language and integrate seamlessly with WordPress. These
        can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/)
        or can be cost-based plugin from a third-party. will server as a development
        plugin (or featured plugin) for the changes post 5.0.
      *  – Site Customization.
         – Enhancements to the Gutenberg editor.
      * The user flow needs to be polished to match something like that:
      *  – When you install 5.0, the Gutenberg plugin is disabled automatically with
        a notice.
         – If you want to continue opting-in to the development version of
        Gutenberg, you’ll have to reactive the plugin again.
         - ![](https://secure.gravatar.com/avatar/a2690bc3e7ef0350cac88e27809169288b0086b1714707655fd2635026a0670b?
           s=32&d=mm&r=g)
         -  [noisysocks](https://profiles.wordpress.org/noisysocks/)  9:08 pm _on_ 
           October 3, 2018
         - I’m wondering, how will we backportbackport A port is when code from one
           branch (or trunk) is merged into another branch or trunk. Some changes in
           WordPress point releases are the result of backporting code from trunk to
           the release branch. urgent bugbug A bug is an error or unexpected result.
           Performance improvements, code optimization, and are considered enhancements,
           not defects. After feature freeze, only bugs are dealt with, with regressions(
           adverse changes from the previous version) being the highest priority. fixes
           to old versions of a package if a newer version is being developed in the
           packages repository? For example, say that WordPress uses `@wordpress/components`
           v1.0.0, `@wordpress/components` v2.0.0 is what is currently in the package
           repository’s `master` branchbranch A directory in Subversion. WordPress 
           uses branches to store the latest development code for each major release(
           3.9, 4.0, etc.). Branches are then updated with code for any minor releases
           of that branch. Sometimes, a major version of WordPress and its minor versions
           are collectively referred to as a "branch", such as "the 4.0 branch"., and
           that there’s an urgent bug that necessitates a v1.0.1 release.
            * ![](https://secure.gravatar.com/avatar/a61af5cd9a78137214c3f0b276a3d07bdb931397f4d7861ce6b818fd062b542d?
              s=32&d=mm&r=g)
            *  [gziolo](https://profiles.wordpress.org/gziolo/)  7:07 am _on_ October
              15, 2018
            * The good part about the approach we took is that we tagtag A directory
              in Subversion. WordPress uses tags to store a single snapshot of a version(
              3.6, 3.6.1, etc.), the common convention of tags in version control systems.(
              Not to be confused with post tags.) every release through Lerna so technically
              speaking you can check out older version locally, apply changes by cherry
              picking commits and publish a new version to npm when necessary. This
              would be similar to what we did in the past with GutenbergGutenberg The
              Gutenberg project is the new Editor Interface for WordPress. The editor
              improves the process and experience of creating new content, making writing
              rich content much simpler. It uses ‘blocks’ to add richness rather than
              shortcodes, custom HTML etc.
               [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/)
              pluginPlugin A plugin is a piece of software containing a group of functions
              that can be added to a WordPress website. They can extend functionality
              or add new features to your WordPress websites. WordPress plugins are
              written in the PHP programming language and integrate seamlessly with
              WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/)
              or can be cost-based plugin from a third-party. release candidates. I’m
              sure we will figure out something as soon as such issue pops up 🙂
         - ![](https://secure.gravatar.com/avatar/4358d28c1e85f9015cb3363e024e2b238bccb44d05c4b84e9a38aafef0d83ac9?
           s=32&d=mm&r=g)
         -  [Riad Benguella](https://profiles.wordpress.org/youknowriad/)  10:13 pm
           _on_ October 3, 2018
         - That’s a good question [@noisysocks](https://profiles.wordpress.org/noisysocks/)
           and part of the workflow we need to polish for post 5.0.
         -  – One way to approach this is to use branches
            – Another way is to use 
           feature flags where the new features are hidden unless you opt-in (pluginPlugin
           A plugin is a piece of software containing a group of functions that can
           be added to a WordPress website. They can extend functionality or add new
           features to your WordPress websites. WordPress plugins are written in the
           PHP programming language and integrate seamlessly with WordPress. These 
           can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/)
           or can be cost-based plugin from a third-party.).
 15. ![](https://secure.gravatar.com/avatar/f9c0b47ea524e59f657e43ae3072761646776db79f688de947778c355e9b7bae?
     s=32&d=mm&r=g)
 16.  [Justin Kopepasah](https://profiles.wordpress.org/kopepasah/)  7:34 am _on_ October
     11, 2018
 17. [@youknowriad](https://profiles.wordpress.org/youknowriad/) if the plan is to 
     continue development from the GutenbergGutenberg The Gutenberg project is the 
     new Editor Interface for WordPress. The editor improves the process and experience
     of creating new content, making writing rich content much simpler. It uses ‘blocks’
     to add richness rather than shortcodes, custom HTML etc.
      [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/)
     repository after merging into coreCore Core is the set of software required to
     run WordPress. The Core Development Team builds WordPress. and releasing WordPress
     5.0, then what types of Core JavaScriptJavaScript JavaScript or JS is an object-
     oriented computer programming language commonly used to create interactive effects
     within web browsers. WordPress makes extensive use of JS for a better user experience.
     While PHP is executed on the server, JS executes within a user’s browser. [https://www.javascript.com](https://www.javascript.com/)
     development will reside under the official WordPress Develop repository (i.e. `
     git://develop.git.wordpress.org/`)?
 18. Are we to consider these two separate pieces of WordPress in the foreseeable future?
 19.  * ![](https://secure.gravatar.com/avatar/4358d28c1e85f9015cb3363e024e2b238bccb44d05c4b84e9a38aafef0d83ac9?
        s=32&d=mm&r=g)
      *  [Riad Benguella](https://profiles.wordpress.org/youknowriad/)  7:54 am _on_
        October 11, 2018
      * For the time being, we should consider these as two separate repositories that
        constitute WordPress when assembled.
      * A secondary goal of GutenbergGutenberg The Gutenberg project is the new Editor
        Interface for WordPress. The editor improves the process and experience of 
        creating new content, making writing rich content much simpler. It uses ‘blocks’
        to add richness rather than shortcodes, custom HTML etc.
         [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/)
        is to be CMS agnostic and even backend agnostic, using a separate repository
        allows us to avoid “shortcuts” which would harm those secondary goals. Also,
        keeping the pluginPlugin A plugin is a piece of software containing a group
        of functions that can be added to a WordPress website. They can extend functionality
        or add new features to your WordPress websites. WordPress plugins are written
        in the PHP programming language and integrate seamlessly with WordPress. These
        can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/)
        or can be cost-based plugin from a third-party. in GithubGitHub GitHub is a
        website that offers online implementation of git repositories that can easily
        be shared, copied and modified by other developers. Public repositories are
        free to host, private repositories require a paid subscription. GitHub introduced
        the concept of the ‘pull request’ where code changes done in branches by contributors
        can be reviewed and discussed before being merged by the repository owner. 
        [https://github.com/](https://github.com/) allows us to keep the rapid pace
        of development for the next phases.
      * This means the JavaScriptJavaScript JavaScript or JS is an object-oriented 
        computer programming language commonly used to create interactive effects within
        web browsers. WordPress makes extensive use of JS for a better user experience.
        While PHP is executed on the server, JS executes within a user’s browser.
         
        [https://www.javascript.com](https://www.javascript.com/) that leaves in the
        develop repository will be mainly what I call “Glue JavaScript”: making sure
        the generic packages fit together and provide the necessary configs from the
        WordPress backend.
      * Keeping these repositories separate should be seen as a pragmatic solution 
        for the moment, it doesn’t mean we can change that in the future.
         - ![](https://secure.gravatar.com/avatar/f9c0b47ea524e59f657e43ae3072761646776db79f688de947778c355e9b7bae?
           s=32&d=mm&r=g)
         -  [Justin Kopepasah](https://profiles.wordpress.org/kopepasah/)  8:17 am 
           _on_ October 11, 2018
         - Thanks for the clarification. 🙂

Comments are closed.

# Post navigation

[← PHP Meeting Recap – September 24th](https://make.wordpress.org/core/2018/10/01/php-meeting-recap-september-24th/)

[A Plan for 5.0 →](https://make.wordpress.org/core/2018/10/03/a-plan-for-5-0/)