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

Tue Jan 13 01:54:40 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:
------------------------------+--------------------------
Description changed by youknowriad:

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).
>
> > 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.

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).

--

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