[wp-trac] [WordPress Trac] #64393: Change how we include Gutenberg in Core

Tue Jan 13 01:52:45 UTC 2026

#64393: Change how we include Gutenberg in Core
------------------------------+--------------------------
 Reporter:  youknowriad       |       Owner:  youknowriad
     Type:  task (blessed)    |      Status:  reopened
 Priority:  high              |   Milestone:  7.0
Component:  Build/Test Tools  |     Version:
 Severity:  blocker           |  Resolution:
 Keywords:  has-patch         |     Focuses:
------------------------------+--------------------------

Old description:

> When we setup the initial architecture and dependencies between Gutenberg
> and Core, Gutenberg was still considered a post content editor. It was
> setting at the same level of abstraction as TinyMCE. This assumption let
> to the use of npm packages to backport code from the Gutenberg repository
> into Core.
>
> The reality though is that this assumption is not valid for some time
> now:
>
>  - Gutenberg includes a lot of iterations to PHP code base: endpoints,
> pages, menu items, block supports, block server side rendering,
> theme.json rendering
>  - The Gutenberg repo outgrow the "post content" for some time now and it
> now powers multiple pages in wp-admin, multiple extensions to existing
> pages...
>
> During all that time, we "hacked" the process to accommodate some of
> this:
>
>  - We have a lot of manual php backports
>  - We do some automatic renames to php functions
>  - We have npm packages that contain both php and JS
>  and a lot more "hacks".
>
> In WordPress 7.0, we'll have a new addition to the Gutenberg repository
> that will force us to either add a new "hack" or reconsider the process.
> We'll have a new "font library" page added to wp-admin and the way it's
> being added is by using a new tool called `@wordpress/build` that
> automatically registers WP-Admin pages and uses "routes" to power these
> pages. This is a generalization of what we've been doing before for the
> site editor (and to some degree the post editor) to allow for easier
> iteration, scalability and extensibility.
>
> The build tool is likely to grow as well to absorb newer more and more
> extensibility points (or concepts) that don't exist today: Blocks,
> dashboard widget, field collections (these are just ideas at this point).
>
> The question becomes how do we backport these to Core (routes, generated
> pages, ...). I see two options in front of us:
>
>  - Continue adhoc backports, copy the generated "php" code from the build
> folder of Gutenberg manually, sync the "routes" folder manually from
> Gutenberg and have some kind of build process on Core to recreate the
> same code. Very likely to create sync issues and more.
>  - Reconsider how we "embed" Gutenberg into Core.
>
> I'm proposing that we take some time to explore the second option here
> and potentially simplify the whole process. What if we make Gutenberg a
> git submodule of WordPress Develop, pin the submodule to the Gutenberg
> branch that we want to include in Core (wp/* release branches) and update
> Core's build tooling to just call Gutenberg's (most of the time).
>
> I'm sure there are a lot more complexities to be discovered here. But I
> also see a lot of potential to both address the "routes" problem but also
> streamline some of the current php backports (not all of them).

New description:

 When we setup the initial architecture and dependencies between Gutenberg
 and Core, Gutenberg was still considered a post content editor. It was
 setting at the same level of abstraction as TinyMCE. This assumption let
 to the use of npm packages to backport code from the Gutenberg repository
 into Core.

 The reality though is that this assumption is not valid for some time now:

  - Gutenberg includes a lot of iterations to PHP code base: endpoints,
 pages, menu items, block supports, block server side rendering, theme.json
 rendering
  - The Gutenberg repo outgrow the "post content" for some time now and it
 now powers multiple pages in wp-admin, multiple extensions to existing
 pages...

 During all that time, we "hacked" the process to accommodate some of this:

  - We have a lot of manual php backports
  - We do some automatic renames to php functions
  - We have npm packages that contain both php and JS
  and a lot more "hacks".

 In WordPress 7.0, we'll have a new addition to the Gutenberg repository
 that will force us to either add a new "hack" or reconsider the process.
 We'll have a new "font library" page added to wp-admin and the way it's
 being added is by using a new tool called `@wordpress/build` that
 automatically registers WP-Admin pages and uses "routes" to power these
 pages. This is a generalization of what we've been doing before for the
 site editor (and to some degree the post editor) to allow for easier
 iteration, scalability and extensibility.

 The build tool is likely to grow as well to absorb newer more and more
 extensibility points (or concepts) that don't exist today: Blocks,
 dashboard widget, field collections (these are just ideas at this point).

 The question becomes how do we backport these to Core (routes, generated
 pages, ...). I see two options in front of us:

  - Continue adhoc backports, copy the generated "php" code from the build
 folder of Gutenberg manually, sync the "routes" folder manually from
 Gutenberg and have some kind of build process on Core to recreate the same
 code. Very likely to create sync issues and more.
  - Reconsider how we "embed" Gutenberg into Core.

 I'm proposing that we take some time to explore the second option here and
 potentially simplify the whole process. What if we make Gutenberg a git
 submodule of WordPress Develop, pin the submodule to the Gutenberg branch
 that we want to include in Core (wp/* release branches) and update Core's
 build tooling to just call Gutenberg's (most of the time).

 I'm sure there are a lot more complexities to be discovered here. But I
 also see a lot of potential to both address the "routes" problem but also
 streamline some of the current php backports (not all of them).

 > Per GB#74490 (comment) this will require more frequent changes to build
 tools in WP-Dev
 I don't understand this, this basically means that it's easier to update
 the build tool, while previously it was duplicated between Gutenberg and
 Core, now it's using the same build tool. So this is more like pro to me.

 > Administratively

 This seems more related to how we approach iterations and work in general
 during alpha period. I prefer commit early and fix quickly rather than
 leaving a huge PR at the least moment before beta 1, but maybe better
 discussed separately. Something that is largely missing here and I that I
 personally felt was disregarded is that this is the result of months of
 work on the Gutenberg repository with testing on both Gutenberg repository
 and third-party plugins. Sure bringing to Core is another step, but it's
 also a step that shouldn't disregard all the iterations that happened
 before.

 > The issue I am seeing is that this is making it very difficult to do
 development confidently in the WordPress-Develop repository. While these
 changes remain in this repo in an incomplete state, it's not possible to
 know where an error is coming from.

 Again, I'm happy to get reviews on the follow-ups and ship them. At this
 point I'm personally very satisfied with how this is working to be honest.
 Outside a couple of fixes, the rest seems like enhancements to me that I'm
 committing to doing in the next days.

 The crux of the change: move from npm packages to checkout and build is
 working perfectly.

 > As mentioned above, this is introducing a significant hinderance for the
 development of code in WordPress-Develop.

 I've spent a long time discussing with @dmsnell today to understand his
 struggles. We discussed a few things:

  - The fact that the block parsing code is split between Gutenberg and
 Core is problem that can be solved separately by moving this code entirely
 to Core.
  - The difference in opinion on whether vendor php code should be
 versioned in consumer repositories or not. It's fair to say that the
 practice in most php repositories is to gitignore dependencies. It's not a
 hill I'm willing to die on, as much as I hate seeing unrelated changes in
 my diffs, if you all prefer it that way, this part is something we can
 revert.

 I've also spent some time with @TobiasBg mentioned above to understand his
 own issues and we've addressed these in the last PR as well, which should
 also hopefully fix the issues you're raising @desrosj

 I'm happy to look at any other thing you consider "hinderance" that I'm
 not seeing right now.

--

Comment (by youknowriad):

 Thanks for the summary :)

 > Build now includes 17 package.json files

 I asked about this above, how is this a problem?

 > Build now includes 172 *.map files, most referencing files that don't
 exist

 This is about adding the svn ignore properties which I'm going to take
 care of.

 > Building results in Gutenberg directory being dirty, preventing
 subsequent updates
 > install-changed doesn't include gutenberg hash in packagehash.txt,
 outdated dependencies aren't detected

 These are both addressed in the latest PR

 > changes are difficult to review, as a result it's easier for Gutenberg
 Experiments and other unintentional changes to end up in Core (as seen
 with Navigation block)

 This is for me something that was missed in Gutenberg PR review rather
 than a result of this change, it can happen for any change including JS
 changes that were gitignored before.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64393#comment:79>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform