Change how we include Gutenberg in Core

[youknowriad]

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

[swissspidy]

Did someone say monorepo? :D

I suggest bringing this up in dev chat to discuss the best path forward with evaluating this. Dedicated Slack meetings or even video calls, followed by a concrete make/core proposal would be helpful. We can come back to Trac once there's a plan :)

[youknowriad]

Monorepo requires a lot more work: aligning trac and GitHub issues, updating workflows releases, tests... While it would also be a solution, it's not one that can happen in time for 7.0 and the above is needed for 7.0. It's a programmatic proposal.

I think what we need is technical explorations at this point.

[swissspidy]

Keep in mind that the source of truth is Subversion still, we can't simply add a git submodule to wordpress-develop, which is just a Git mirror

[youknowriad]

Keep in mind that the source of truth is Subversion still, we can't simply add a git submodule to wordpress-develop, which is just a Git mirror

Not planning to change that, but a git submodule (or an svn external for that matter) is similar to an npm package, it's an external dependency you bring during the project initialization.

[ellatrix]

Instead of a git submodule, could it just be an empty folder that the build process uses to checkout Gutenberg?

[youknowriad]

Instead of a git submodule, could it just be an empty folder that the build process uses to checkout Gutenberg?

Yes, that works for me. I'm not really opinionated about how we fetch the Gutenberg repository itself, important part is to treat it as a single external dependency (instead of multiple small ones like today)

[isabel_brison]

Instead of a git submodule, could it just be an empty folder that the build process uses to checkout Gutenberg?

The main difference I see between these two options is that, if we intend Core to use PHP files stored in Gutenberg directly, with the empty folder strategy it will no longer be possible to run the PHP parts of Core without a build step.

I guess my question is how do we determine which PHP files live in Gutenberg and which in Core. For instance, it might make sense for all the editor-related files such as block supports to live in Gutenberg, as they're closely tied to the JS (and currently they're duplicated across both codebases).

But if we intend to continue using the Gutenberg plugin as an experimental development platform there will still be a need to filter, extend or override parts of the Core PHP from time to time so new features can be tested in the plugin. So from that perspective it's unlikely we'll ever fully resolve the problem of porting PHP changes from Gutenberg to Core.

[ellatrix]

with the empty folder strategy it will no longer be possible to run the PHP parts of Core without a build step

Not sure if I see a difference between the two. A git module would still require the same step in an svn repo?

I guess my question is how do we determine which PHP files live in Gutenberg and which in Core.

Yes, I don't think this solution aims to fully solve PHP "backports". The way I see it is that we'd still require a hook in Gutenberg and a "backport" in core, even though they're pretty much added at the same time. The Gutenberg plugin will also still have to run without WP trunk, on the current WP version. But what it does solve is removing the need for npm package syncs, and backporting PHP changes at a later time (this pretty much forces us to commit both at the same time).

[isabel_brison]

A git module would still require the same step in an svn repo?

I was assuming that the git module would translate to an svn external in the svn repo and it would "just work" but I may be wrong :)

But what it does solve is removing the need for npm package syncs, and backporting PHP changes at a later time

Absolutely, if we can solve this just for package-related code it will make our lives much easier.

Trac ticket: https://core.trac.wordpress.org/ticket/64393

## Summary

This PR changes WordPress Core's Gutenberg integration from npm packages to a checkout-and-build approach. Instead of syncing individual npm packages, Core now checks out the Gutenberg repository, builds it, and copies the build artifacts. This enables Core to use Gutenberg's advanced features like route-based navigation, full-page rendering, and the new Font Library. But also offers us the possibility to streamline more backports later (an example in this PR is the automatic copy of theme.json file). Check the issue for more details on the issue at hand.

## New Build Pipeline

1. Checkout: npm run gutenberg:checkout clones Gutenberg at a specified ref
2. Build: npm run gutenberg:build runs Gutenberg's build process
3. Copy: npm run gutenberg:copy copies and transforms build output to Core
4. Integrate: npm run gutenberg:integrate runs all three steps

## What Gets Copied

From Gutenberg build to Core:

• /build/routes/ → /src/wp-includes/build/routes/
• /build/pages/ → /src/wp-includes/build/pages/
• /build/modules/ → /src/wp-includes/js/dist/script-modules/
• /build/scripts/ → /src/wp-includes/js/dist/
• /build/styles/ → /src/wp-includes/css/dist/
• /build/blocks/ → /src/wp-includes/blocks/

## Path Transformations

The copy script transforms Gutenberg plugin paths to Core paths:

• plugins_url() → includes_url()
• plugin_dir_path() → ABSPATH . WPINC . '/build/'
• Boot module paths adjusted for Core's directory structure
• Enqueue conditions work with both menu pages and direct file access

Ideally these transformations shouldn't be needed, maybe we can make our "build" tool more generic to streamline the integration better and allow "building for core" directly. I'll look into that separately.

## Webpack Changes

Removed webpack configs that are now replaced by Gutenberg's build:

• ❌ tools/webpack/blocks.js - Using Gutenberg's block builds
• ❌ tools/webpack/packages.js - Using Gutenberg's script builds
• ❌ tools/webpack/script-modules.js - Using Gutenberg's module builds
• ❌ tools/webpack/development.js - Using Gutenberg's dev builds
• ❌ tools/webpack/vendors.js - Using Gutenberg's vendors
• ✅ tools/webpack/media.js - Kept (Core-specific files). to be honest, I'm not really sure if Webpack is needed for these files but I kept it unchanged for now, we could decide to remove the webpack dependency later entirely.

## Font Library Integration

Added /wp-admin/font-library.php as the first proof-of-concept using this new architecture.

### Some other changes.

src/wp-includes/script-modules.php

• Removed outdated debug version handling for @wordpress/interactivity (this has been removed from Gutenberg)

Gruntfile.js

• Added a vendor copy step that was previously done in webpack/packages.js

package.json

• The "hash" or Gutenberg version used is defined here. Right now I picked a recent Gutenberg commit but this is likely to refer commits in wp/* release branches in Gutenberg.

## Testing

• There should be no big disruptions in the core development workflow. I tried to keep the flow the same, the output files in the same places...
• The initial build might be slow because of typescript building, the next ones should be ok.

---

I think there are a lot of simplifications we could do later (specially to the copy script) by aligning the folder structures more closely together (the build folder of Gutenberg, and the file structure for built scripts, styles, modules, pages... on Core). It does require changing some paths on Core. I do think it would be for the better but I kept it out of this PR.

Looks like there's an infinite loop because wp-build use time based hashes which triggers the "commit unsaved changes" on each commit. I'm going to disable that workflow temporarily.

This is exciting! Also paves the way to run Gutenberg e2e tests :)

What I like about this process is that it actually clarifies what it takes to "integrate Gutenberg into Core" it all happens in a single command. While previously it was scattered all over the place.

Ok I think this is ready to land personally. I'd love reviews though :)

[ellatrix]

Approved on Github: Works great and makes a lot of sense. Let's try it. 🙂

I've started to take a look at this, but it's a pretty big PR and I need a bit more time.

Is this a blocker for anything specific? Or is there room for a few more days to review?

Can wait for a few more days. Maybe we should aim to land it early next week.

I gave this a test run on my local env and it's working really well so far! I did have to point the env to the build directory (the default in the .env file is src) and then of course npm run build.

Without having looked extensively at the code yet, I love the direction! It will save us so much manual work in porting code from Gutenberg to Core ❤️

I thought npm run build was meant to build the "build" folder and npm run dev was for the "src" folder. Now, it's possible that this assumption is wrong and I'm happy to correct my scripts if needed. It's really unclear to me what script is supposed to target which output folder.

I thought npm run build was meant to build the "build" folder and npm run dev was for the "src" folder

Yes that's correct! The ​WORKING_DIR is set to src whenever the dev flag is passed. So:

• npm run dev watches the src folder
• npm run build:dev builds the src folder
• npm run watch watches the build folder
• npm run build builds the build folder

With this PR, I wasn't able to get my env running or build it from the src directory, it only worked from the build one. I thought I'd mention that in the comment so other folks who test it don't run into the same issue.

I just tried and confirmed that both npm run dev and npm run build:dev work for me with the default "src" environment.

@desrosj Hi Jonathan, did you have time to look at the PR. I'd love to avoid letting it sit for too long. Regardless, I'll be available for any follow-ups...

I did not get to look much further.

One suggestion I was going to make was around the new files that are replacing old ones that did the same thing. For example, managing packages. I was going to suggest that those are added to version control using an svn copy, and then all of the changes be applied.

While ya a new approach, this maintains the history of those files so that a visual comparison is available instead of just a sea of red and green in separate files.

One suggestion I was going to make was around the new files that are replacing old ones that did the same thing. For example, managing packages. I was going to suggest that those are added to version control using an svn copy, and then all of the changes be applied.

While this is a new approach, this maintains the history of those files so that a visual comparison is available instead of just a sea of red and green in separate files.

Thanks for quickly chiming in, I guess what you're saying is that we shouldn't git ignore the files that come from Gutenberg.

I found that the previous approach of gitignoring some files (JS, CSS) and no others (PHP, JSON) was not very consistent and also created a lot of confusion of where the source of truth of these files is. I think with the changes in this PR, it's a lot more clear. These are external dependencies maintained in Gutenberg.

Sorry, I'm not at my computer currently, so that was poorly worded without an example. That comment was specifically targeted at any files within the tools directory only.

Ah I see :) Thanks for clarifying. It makes more sense now. I don't really think there's a 1 to 1 relationship with what was being done before though, so it's a bit hard to think of this as "file renames", it's a completely different pipeline.

Given the holidays and all, I decided to let this sit for a few more days. We do need to ship it soon enough before 7.0 beta 1 so I'm planning to do that early January, everyone will be back and we'll have time before 7.0 to polish. I don't really expect any major issues, just taking the safe road here.

[youknowriad]

In 61438:

Build: Update Gutenberg integration to checkout-and-build approach.

This changes WordPress Core's Gutenberg integration from npm packages to checking out and building Gutenberg directly. Instead of syncing individual npm packages, Core now checks out the Gutenberg repository, builds it, and copies the build artifacts.

This enables Core to use Gutenberg's advanced features like route-based navigation, full-page rendering, and the Font Library, while also streamlining future updates.

New commands:

• npm run gutenberg:checkout - Clones Gutenberg at a specified ref
• npm run gutenberg:build - Runs Gutenberg's build process
• npm run gutenberg:copy - Copies and transforms build output to Core
• npm run gutenberg:integrate - Runs all three steps

Main changes:

• Removes webpack configs replaced by Gutenberg's build (blocks.js, packages.js, script-modules.js, development.js, vendors.js)
• Adds Font Library page (/wp-admin/font-library.php)
• Adds copy scripts to transform Gutenberg plugin paths to Core paths
• Moves vendor copy step from webpack to Gruntfile

New year, new process. Happy New Year!

Props youknowriad, ellatrix, sirreal, westonruter, desrosj, tellthemachines.
Fixes #64393.

This fixes a couple of issues raised by @swissspidy on the Gutenberg integration script.

• It restores the theme.json i18n file for wp-cli to work properly.
• It renames gutenberg_ prefixes to wp_

Trac ticket: [](https://core.trac.wordpress.org/ticket/64393)

[youknowriad]

In 61439:

Build/Test Tools: Fix Gutenberg integration script prefixes and theme-i18n.json handling.

This changeset addresses two issues in the Gutenberg integration workflow:

• Sets wpPlugin.name to wp in build-gutenberg.js so generated PHP files use wp_ prefixes instead of gutenberg_.
• Persists theme-i18n.json in the repository for WP-CLI compatibility, as this file is required but was being ignored.

Props youknowriad, swissspidy.
See #64393.

[peterwilsoncc]

Reopening as this has broken the build.

It works fine if define( 'SCRIPT_DEBUG', true ); is included in the config file but if it's set to false/uses the default value the styles do not load as many of the *.min.css files have been removed.

See screen shot above. Trac won't display the combined diff due to the size but the affect can be seen on GitHub's clone of the build repo ​WordPress/WordPress@4d2234f...49339b2.

Bumping the priority due to the need for a fix.

[peterwilsoncc]

I've created a draft ​pull request which appears to fix the issue. I am far from confident it won't have unintended side effects so haven't marked it ready for review.

In addition to the issue above:

• I've noticed that the SVN properties were not updated so running npm run build in the svn repo results in a dirty repo. Very dirty as the directory that is been included includes the entire Gutenberg git repository.
• .map files have been added to the build repo in ​https://build.trac.wordpress.org/changeset/60750, they're not usually included in the distribution.

Having reviewed the changes further, I am strongly inclined to revert the commits on this ticket.

My primary issue is that not enough time was given for people to review the pull request. While it was opened on December 16, the majority of contributors have been absent from December 19 through to the new year. Effectively the PR was only open for three or four business days. Some of the busiest business days of the year.

Secondly, I don't think the changes were tested anywhere near closely enough. The Playground link on the originating pull request showed the issue but it went unnoticed. Catching this issue was literally two clicks away from the PR and it wasn't done.

[youknowriad]

Thanks Peter for spotting that and for the follow-up. This is exactly why we need this commit to land early before beta, so it gets as much testing as possible which may or may not be caught in PRs.

For the issue itself, the main problem is that Gutenberg and Core have different expectations for built CSS. In Gutenberg only one file is built, Core expects both. For JS on the other side they both built two files. So a good path here is to make the behavior consistent. It should be a smallish a change, I'll be working on it today.

Trac ticket: https://core.trac.wordpress.org/ticket/64393

## Description

Updates the Gutenberg hash to include WordPress/gutenberg#74380, which fixes the CSS build to generate both minified (.min.css) and non-minified (.css) versions. Previously, Gutenberg only produced a single CSS file, causing 404s when SCRIPT_DEBUG is false (Core expects .min.css files).

## Testing

1. Run npm run ​build:dev
2. Verify both style.css and style.min.css exist in src/wp-includes/blocks/*/
3. Test with SCRIPT_DEBUG=true and SCRIPT_DEBUG=false — editor should load correctly in both cases

The dea73 commit points to somewhere in a branch? The corresponding trunk commit is 4856d5d1842.

The dea73 commit points to somewhere in a branch? The corresponding trunk commit is 4856d5d1842.

Good catch, that's the commit in the extinct fix/build-tool-old-hash-do-not-remove-branch branch

[youknowriad]

In 61446:

Build/Test Tools: Update Gutenberg hash to fix CSS minification.

Updates the Gutenberg ref to include changes that generate both minified and non-minified CSS files during build. Previously, the build only produced a single CSS file (e.g., style.css), causing missing asset errors when SCRIPT_DEBUG is set to false, as Core expects .min.css files.

Props peterwilsoncc, dd32, tyxla, jsnajdr, mcsf.
Fixes #64393.

[youknowriad]

The main minified file issue should be fixed in the last commit, that said, I didn't update the svn:ignore yet. I looked at it and it seems very different from the .gitignore, so I'm not really sure why is it the case.

Here are the list of new gitignored files

/gutenberg
/src/wp-includes/blocks/*
!/src/wp-includes/blocks/index.php
/src/wp-includes/build
/src/wp-includes/class-wp-block-parser.php
/src/wp-includes/class-wp-block-parser-block.php
/src/wp-includes/class-wp-block-parser-frame.php
/src/wp-includes/theme.json

[dmsnell]

The checkout-gutenberg.js script unconditionally checks out the Gutenberg repository; after checking out it contains 1.8 GB on my machine as I write this comment.

It makes multiple rounds of git fetching and introduces network dependencies into the Core development workflow, making a build fail when unable to reach the Internet.

This has added many minutes to my local build, which otherwise is practically instant with php -S 0.0.0.0 -t ./src. Core already required building the JS files, but this adds another step which is serial, unnecessary for typical development, and network-dependent. (Whereas previously, letting those JS files stagnate caused very little impediment to development on unrelated files, this new step adds the build unconditionally and thus obstructs where the previous didn’t).

It also seems to run git checkout FETCH_HEAD which could be combined into the previous fetch, which could be combined into the previous clone.

The npm ci step is particularly heavy, which in the case of building a release or running CI jobs seems very appropriate, but it intentionally deletes all 1.8 GB of packages, reruns the dependency resolution when it doesn’t need to, re-downloads every package, and builds everything, when nothing has changed or needs to change. This could be avoided by a number of different mitigations, including an optimization that checks if any of this work is necessary before doing it on every build.

I would like to propose that we add these steps for now only with the addition of some new CLI arg or ENV value. It’s too costly to introduce this overhead for every change or invocation of any development server, and why not make it opt-in to isolate the impact to where its value is greatest?

[dmsnell]

I should note as well that this has basically trashed my ability to develop on Core without multiple minutes of lag between every change. I never had to run npm run dev before, but now I have to or else WordPress crashes with the message to build the files.

This needs resolving IMO, and something that I think is uncovered with brief and basic testing. The page WordPress provides which instructs to run npm run build no longer works reliably; when I follow its steps I’m left seeing the same page, unable to load WordPress. This is discouraging me greatly.

While I support the monumental work to better converge Gutenberg with Core, I am concerned about sweeping changes like this being made without broader understanding of the impact on different parties. We know there will be pain, so let’s do everything we can to avoid dumping it unnecessarily on bystanders.

This updates the Gutenberg build integration to use the new --fast flag, which skips TypeScript-related steps (version validation, tsc --build, and type declaration checks) that aren't needed when building for WordPress Core. These steps only produce .d.ts type declaration files which aren't shipped with Core.

The Gutenberg ref is also updated to include the commit that adds the --fast flag support.

For reference, I compared the build step in three jobs:

1- ​Before the move to the new integration flow 1m19 seconds
2- ​After the move to the new integration flow 6m17 seconds
3- ​After this PR 1m49 seconds

So I think with this PR we're effectively back to similar decent performance levels for the build commands and comparable to previous jobs without losing the benefits for the "checkout & build" approach.

[swissspidy]

We also need to talk about how this negatively affects ​https://developer.wordpress.org/reference/

Now that many classes and functions no longer exist in trunk without a build step, this probably breaks pages like ​https://developer.wordpress.org/reference/classes/wp_block_parser_block/

[dmsnell]

All, as I tend to do from time to time I overreacted and was needlessly emotionally charged when I wrote my comments. I apologize for any disrespect I showed towards @youknowriad or others working on this.

In response I’ve updated my comments to better reflect what I hope is more helpful commentary, summarized here:

• Can we ensure that we find a way to make Core build without introducing network dependencies after cloning? or certainly after having run npm install? As someone who frequently works tethered to a capped data plan, it’s not sustainable for me to wait for hundreds of megabytes of compressed JS files to download and build when working.
• Can we adjust this so that nothing more than an absolutely minimum build is required for WordPress to function? Releases cannot have stale files, but I work productively in stale files all the time. I am not 100% always on the latest trunk, and I will not always have the latest JS files built either, but that doesn’t impede me from working on email, or HTML safety, or on web standards support. If and when I realize that things are broken I can choose to run the update and the build.
• Can we immediately stop running multiple git fetches, especially when they aren’t necessary. git is immutable, and if we have the ref there’s no need to try to fetch it again. At a minimum, if we have a commit SHA it’s essentially free to check if the ref is already fetched.
• Similarly, can we avoid running npm ci if the ref is unchanged since the last run? or ideally gate it behind a CLI arg or an ENV value so that it doesn't constantly run and download and reinstall packages?

[dmsnell]

Now that many classes and functions no longer exist in trunk without a build step, this probably breaks pages

@swissspidy what’s the mechanism here? is it because the API docs don’t run the build process?

For balance, our API docs have been broken and have not updated since WordPress 6.7.0 and many classes are already missing or stale, so there is plenty of work there beyond this.

[dmsnell]

​An unrelated PR is failing on the new step because of a network issue when running npm install. GitHub’s log shows ECONNRESET.

Might be good to monitor the ratio of flakey test failures and if this is a coincidental fluke or if the new network dependencies are going to make a notable impact.

[johnbillion]

To add to the above concerns, the addition of npm run build:dev in the GitHub Actions workflows adds 6 minutes to every PHPUnit test job and Local Docker Environment test job. The PHPUnit tests have gone from taking ~16 minutes to taking ~22 minutes.

[dmsnell]

Some of my normal scripts which run on a fresh checkout of wordpress-develop no longer work, because the PHP files are missing without the build step.

This particularly affects my benchmarking scripts, which is what led me to this now (I did not set out looking to find problems with it). My benchmarking of WordPress releases and HTML API and other performance-related changes involves running tests for hours, as it is, flipping between fresh database and code states.

With the addition of the build step this is multiplying my required test runtimes into days and more.

This is all due to the PHP files which were removed from the repository and then added to .gitignore. Could we leave the PHP files intact so that Core isn’t missing necessary classes on a checkout? And then when we pull in the code from Gutenberg, allow for those “backports” to also update the version-controlled files? Surely we could detect if there were changes in Core that weren’t in Gutenberg with something like git diff PREV_REF...CURRENT_REF -- src/wp-includes/class-wp-block-parser.php as a way to avoid overwriting changes.

[youknowriad]

In 61450:

Build/Test Tools: Use --fast flag for Gutenberg builds.

Adds the --fast flag to Gutenberg build commands, which skips TypeScript-related steps (version validation, tsc --build, and type declaration file checks) that aren't needed when building for WordPress Core. These steps only produce .d.ts files which aren't shipped with Core. Also updates the Gutenberg ref to include the commit that adds --fast flag support.

The build times are now comparable to the build times we had using the npm packages.

Props dmsnell, johnbillion.
See #64393.

[youknowriad]

With the last commits, the build time are back to comparable numbers to before. You can see a recap here ​https://github.com/WordPress/wordpress-develop/pull/10688#issuecomment-3717902779

[youknowriad]

Can we ensure that we find a way to make Core build without introducing network dependencies after cloning? or certainly after having run npm install? As someone who frequently works tethered to a capped data plan, it’s not sustainable for me to wait for hundreds of megabytes of compressed JS files to download and build when working.

I don't see this that different from what we were doing previously as the same code was being downloaded into node_modules and required network dependencies. I guess the main difference is that the heck.

This needs resolving IMO, and something that I think is uncovered with brief and basic testing. The page WordPress provides which instructs to run npm run build no longer works reliably; when I follow its steps I’m left seeing the same page, unable to load WordPress. This is discouraging me greatly.

I'm happy to look at this, I did test this and I can't reproduce personally but again there are multiple flows to develop on WordPress Core and I'm happy to look specifically at your flow.

Trac ticket: https://core.trac.wordpress.org/ticket/64393

Moves Gutenberg checkout to postinstall hook, separating dependency setup from build. Removes checkout step from the build step.

## Benefits:

• Faster build times: checkout happens once at install, not every build (although the script was already accounting for this before)
• Cleaner separation of concerns: dependencies are ready before any build runs

## Test plan

• Run npm install and verify Gutenberg checkout runs automatically
• Run npm run build and verify build completes successfully
• Run npm run ​build:dev and verify dev build works

[youknowriad]

The last PR effectively moves the gutenberg checkout to the npm install (post install script) effectively restoring a very similar flow to what we had before.

Noting that with this PR the "build" step of WordPress takes 30 seconds less than what we used to have before the change in Gutenberg integration. The tradeoff is that the "install" step is a little bit slower. This feels like a win since building is something you do more often and install is done once.

[dmsnell]

Thanks for your follow-up and continuing work on this @youknowriad.

I don't see this that different from what we were doing previously

The main difference is that once those files were built they could remain stale for a very long time. I think occasionally they needed to be rebuilt, perhaps when files were deleted or added. Obviously if the JS files were stale things wouldn’t be 100% right, but I tried to address above how this is different than removing required PHP files.

There is another distinction: prior to this change, with a valid wp-config.php file it was possible to checkout the code and run require __DIR__ . '/src/wp-load.php';. This is how plenty of my scripts are built, and how I do interactive development within the PHP shell, and how my tests run.

After this change, attempting to require wp-load.php crashes because the PHP files aren’t there which Core imports. in other words, trunk is broken without running corrective build steps, which require network access, heavy downloads, and long delays.

---

There’s a coincidence in my reporting because I happened to be drawn to parser work after finding a longstanding issue for a particular kind of malformed post. The git history is gone from the file and I can’t see my changes or scan back in history.

It’s actually worse than before because with Gutenberg as a plugin I could have the files separate and load Gutenberg the plugin. Still, I could modify Core files to explore solutions and then create patches on both sides. Now, however, not only have I lost all version-control information in the PHP files that are now “built” but I also can’t reset those files because they are ignored. I have to manually copy and paste files between projects and files and make sure I don’t get confused.

This is why I think we should at a minimum leave all required PHP files in Core that it needs to run. Moving the npm ci step into the installation is better than running it on every change, but when bisecting, benchmarking, investigating history, it’s still dramatically obstructive.

What is the reason for deleting these files and adding them to .gitignore?

Ideally, Core should work, albeit in a degraded state, without running any build, especially without running npm commands.

[peterwilsoncc]

@youknowriad I've created a test repo that includes only the build changes, ie without commits to wp-dev that are unrelated in the mean time. A comparison of the before and after changes can be seen at ​peterwilsoncc/wp-build-changes-testing@667a28d...main. I'm updating this manually each morning Australian time.

• The *.map files are still being committed to the build, these will need to be removed as they're not referenced in the generated files & the references are to uncommitted code.
• The auto generated functions introduced in ​GB#73877 will need to be correctly prefixed with wp_ - eg font_library_wp_admin_render_page()
• These auto generated files are also very difficult to review
• A new index.php files has been introduced wp-includes/build/routes/index.php - it would be good to avoid this as we've had issues with using index file names in the past, see #60237.
• I'm seeing a few package.json files, eg wp-includes/build/routes/navigation/package.json
• wp_register_development_scripts() has been removed without been deprecated
• The global variables in wp-includes/build/routes.php are unprefixed. It also adds actions in such a way that's it's not possible for third party devs to remove them

These changes also make it very unclear what PHP changes are been introduced. This is a problem as there are often issues picked up during the merge of packages to core. Package bumps will need to provide a diff that can be reviewed for the build effects.

There's a lot going on in these changes so it's probable that I am missing a few things.

We'll also need to consider whether gitignore and SVN props will need to be backported to branches receiving security updates to avoid the accidental commit of the gutenberg repo in to wp-dev.

[youknowriad]

In 61458:

Build: Move Gutenberg checkout to a postinstall script.

This separates dependency setup from the build process by running
the Gutenberg checkout during npm install rather than before each
build. Build times decrease by approximately 30 seconds since the
checkout now occurs once during installation.

Props youknowriad, dmsnell.
See #64393.

Commtted.

[youknowriad]

What is the reason for deleting these files and adding them to .gitignore?

Yes, there is, these files are maintained in Gutenberg, and the source of truth for them is there. So their version history is there. In the same way it doesn't make sense to commit the "vendor" of composer dependency, these are php dependencies but we're just not using composer yet.

Ideally, Core should work, albeit in a degraded state, without running any build, especially without running npm commands.

I think this is not the case for a long time now, if you don't build Core, you get an empty page asking you to build (before and after the commit)

[youknowriad]

These auto generated files are also very difficult to review

The best way to review this is in Gutenberg, we need to review the build tool templates. These functions are not just about Core, they are also about plugins registering their own pages.

I've tracked all the enhancement suggestions that you have in ​https://github.com/WordPress/gutenberg/issues/74488

I'm seeing a few package.json files, eg wp-includes/build/routes/navigation/package.json

Yes, this is expected, What bothers you with this?

I'm seeing a few package.json files, eg wp-includes/build/routes/navigation/package.json

wp_register_development_scripts() has been removed without been deprecated

Restored and deprecated the function here. ​https://github.com/WordPress/wordpress-develop/pull/10702

These changes also make it very unclear what PHP changes are been introduced. This is a problem as there are often issues picked up during the merge of packages to core. Package bumps will need to provide a diff that can be reviewed for the build effects.

This is not needed, this a build tool maintained in Gutenberg with the same guidelines as Core, it's just another repository. Changes are verified there already. Similarly to all the JS, packages and all the dependencies.

We'll also need to consider whether gitignore and SVN props will need to be backported to branches receiving security updates to avoid the accidental commit of the gutenberg repo in to wp-dev.

Since this only affects trunk, I don't think there's anything needed here unless I'm missing something.

The *.map files are still being committed to the build, these will need to be removed as they're not referenced in the generated files & the references are to uncommitted code.

I'm having trouble understanding what exactly need to be svn ignored and what not. Can we instead just map .gitignore as is in svn:ignore? Happy to get some help here as well.

[peterwilsoncc]

I've noticed that changing the Gutenberg hash doesn't trigger the install-changed script to reinstall, this is due to the package ​generating the hash from the dependencies rather than the entire contents of the package.json file.

Reproduction:

1. Run npm ci; npm run build
2. Change the Gutenberg reference in the package file to trunk
3. Run npm run build
4. Observe the script reports package.json has not been modified.

[wildworks]

wp_register_development_scripts() has been removed without been deprecated
Restored and deprecated the function here. ​https://github.com/WordPress/wordpress-develop/pull/10702

I think wp_register_development_scripts() is a function to enqueue the library for react hot reload. If we delete this function or change it to a function that does nothing, won't block developers no longer be able to use hot reload?

[TobiasBg]

It looks like this change is also affecting common plugin unit test setups :-(

For example, I'm ​checking out wordpress-develop to have the WP unit test framework available.
However, when running tests I only get

PHP Warning:  require(/home/runner/work/TablePress/TablePress/src/wp-includes/build/routes.php): Failed to open stream: No such file or directory in /home/runner/work/TablePress/TablePress/src/wp-settings.php on line 245
PHP Fatal error:  Uncaught Error: Failed opening required '/home/runner/work/TablePress/TablePress/src/wp-includes/build/routes.php' (include_path='.:/usr/share/php') in /home/runner/work/TablePress/TablePress/src/wp-settings.php:245
Stack trace:
#0 /home/runner/work/TablePress/TablePress/tests/phpunit/includes/install.php(40): require_once()
#1 {main}
  thrown in /home/runner/work/TablePress/TablePress/src/wp-settings.php on line 245

[peterwilsoncc]

1) When doing an update test to trunk I noticed that the gutenberg/package.json file ends up dirty following a build. When switching back to the initial hash, this resulted in the following error.

Command errors:
error: Your local changes to the following files would be overwritten by checkout:
	package.json
Please commit your changes or stash them before you switch branches.
Aborting

❌ Fetch/checkout failed: git checkout FETCH_HEAD failed with code 1
npm error code 1
npm error path /Users/peterwilson/Sites/wp-dev/wordpress-develop
npm error command failed
npm error command sh -c npm run gutenberg:checkout
npm error A complete log of this run can be found in: /Users/peterwilson/.npm/_logs/2026-01-11T22_25_46_800Z-debug-0.log

This was introduced in r61438 due to the build step changing the package file.

2) When doing the test checkout with trunk, I've noticed that the gutenberg-experiments check introduced in ​Gutenberg@3bf3e488fd is included.

This will mean that if the Gutenberg plugin is disabled without turning off the experiment, the experiment will continue to run in WordPress-Develop.

This is not needed, this a build tool maintained in Gutenberg with the same guidelines as Core, it's just another repository. Changes are verified there already. Similarly to all the JS, packages and all the dependencies.

I agree, this would be the ideal case but it's not the reality. It's common that deprecation errors are caught during the import: either functions removed without proper deprecations (as happened on this ticket), or missing calls to _deprecated_*().

Some merge PRs get a few comments, some get dozens of comments.

The issue I noted above re: the navigation experiment is a case in point.

Since this only affects trunk, I don't think there's anything needed here unless I'm missing something.

I thinking about when switching branches as the gutenberg directory will be left behind so could be committed in error.

I'm having trouble understanding what exactly need to be svn ignored and what not. Can we instead just map .gitignore as is in svn:ignore? Happy to get some help here as well.

The map files and package files I am seeing are generated during the build step so aren't committed to wp-dev. They'll need to be removed in a change to how the build script runs.

---

I am still inclined to revert the commits on this ticket.

It's a huge change and is causing too much friction for people attempting to work on WordPress-Develop.

Frankly, I think it was irresponsible to commit this in the first palce. The PR had had numerous change requests since the initial approval along with numerous commits. It was unsuitable for a YOLO commit.

We're already at four follow up commits and more will need to come.

@jorbin, @johnbillion, @desrosj as build tools component maintainers, I'd value your thoughts.

[youknowriad]

I am still inclined to revert the commits on this ticket.

I think reverting creating more issues that it solves. This change is necessary for features slated for 7.0 and it's better to solve them way before alpha/beta than run to solve them at the last moment.

Also at this point, the workflow is very similar to what we had before, aside some slight changes on what scripts run (wp-build instead of webpack...).

I agree that maybe it was committed a bit too soon but I'm not seeing any major issues at this point to be honest.

[ellatrix]

It's a huge change and is causing too much friction for people attempting to work on WordPress-Develop.

Let's also see things from the other side a bit: it's a huge change that resolves a ton of friction on the Gutenberg dev side. I can't understate how much work and overhead it is every release to sync and merge the Gutenberg codebase into core.

Frankly, I think it was irresponsible to commit this in the first palce.

Worth noting that we're in the alpha stage and commits were made swiftly to resolve issues. It's really hard to make these changes without trying them.

[youknowriad]

In 61472:

General: Restore and deprecate wp_register_development_scripts().

The function was removed in [61438] but should have been deprecated instead of removed outright, per WordPress backward compatibility policy.
Hot reloading is not used anymore in the latest Gutenberg build tool.

Props peterwilsoncc, westonruter.
See #64393.

[youknowriad]

2) When doing the test checkout with trunk, I've noticed that the gutenberg-experiments check introduced in Gutenberg@3bf3e488fd is included.
This will mean that if the Gutenberg plugin is disabled without turning off the experiment, the experiment will continue to run in WordPress-Develop.

This seems unrelated to how the code is integrated. cc @get_dave for awareness and potential follow-up in Gutenberg.

## Trac ticket

https://core.trac.wordpress.org/ticket/64393

## Summary

This PR improves the Gutenberg build integration to address several issues reported in the ticket. The changes simplify the developer workflow and restore a flow similar to how package dependencies worked before the Gutenberg checkout-and-build approach was introduced.

### Key Improvements

1. Automatic rebuild on ref change: Adds a new gutenberg:sync script that follows the same pattern as install-changed (which WordPress already uses for npm dependencies). It stores a hash of the built ref in .gutenberg-hash and only rebuilds when the ref changes. This means when gutenberg.ref in package.json changes (e.g., after git pull), the next npm run build will automatically detect this and rebuild Gutenberg.

2. Full integration on npm install: Updates postinstall to run the complete checkout + build + copy flow. Running npm install now produces a fully working development environment with Gutenberg assets in src/.

3. Conditional PHP file loading: Adds file_exists() checks around the PHP files from wp-includes/build/ (routes.php and pages.php). This prevents WordPress from fatal erroring if these files don't exist yet - addressing concerns from developers who need to run PHP before the build completes.

4. Clean Gutenberg checkout: Restores Gutenberg's package.json after the build completes using git checkout, keeping the Gutenberg directory clean and avoiding uncommitted changes.

5. Simplified scripts: Removes the gutenberg:integrate npm script and gutenberg-integrate grunt task since their functionality is now handled by gutenberg:sync.

### New Flow

npm install
  → gutenberg:sync (checks .gutenberg-hash, runs checkout+build if ref changed)
  → gutenberg:copy --dev (copies to src/)

npm run build / build:dev / dev
  → gutenberg-sync (checks hash, rebuilds only if ref changed)
  → gutenberg-copy (copies to build/ or src/)

This is very similar to how things worked before with package dependencies - npm install handles everything, and subsequent builds are fast because they skip the already-built Gutenberg unless the ref has changed.

## Test instructions

1. Clone the branch and run npm install
2. Verify Gutenberg is checked out, built, and copied to src/
3. Run npm run build - should skip Gutenberg rebuild ("already synced")
4. Change gutenberg.ref in package.json to a different commit
5. Run npm run build - should detect the change and rebuild Gutenberg
6. Delete src/wp-includes/build/routes.php and verify WordPress doesn't fatal error

## Files changed

• .gitignore - Added .gutenberg-hash
• Gruntfile.js - Added gutenberg-sync task, removed gutenberg-integrate task, updated build tasks
• package.json - Updated postinstall, added gutenberg:sync, removed gutenberg:integrate
• src/wp-admin/font-library.php - Updated error message to reference npm install
• src/wp-settings.php - Added conditional file_exists() checks for build PHP files
• tools/gutenberg/build-gutenberg.js - Added restorePackageJson() after build
• tools/gutenberg/sync-gutenberg.js - New script for hash-based rebuild detection

🤖 Generated with ​Claude Code

@TobiasBg has kindly accepted to help me test this PR properly and the unit tests in TablePress are now running without any changes.

[dmsnell]

Here’s a pragmatic proposal: what if we introduced a weekly cadence on this one in order to make it easier to find all the places that are broken but without obstructing everything in the meantime?

1. Immediately revert the entire chain of patches on this issue. This will restore trunk to a working state. Unfortunately this involves resolving merge conflicts in Global Styles: Lift classic block restrictions. ​31e2aaabb because of indexing in $submenu, but this is the point of the revert. The more we keep adding ad-hoc patches to work around the issues the harder it is to isolate the changes and the unintended damage they are causing.

2. Liberally update the build change in a separate branch. Everyone is encouraged to merge this branch into their local development and report issues on this ticket.

3. Every Tuesday we merge the build-change branch into trunk and see if new reports turn up. If they do, we revert the change again and attempt to fix the issues in the build-change branch.

This will add a number of merge/revert commits in trunk, but under the principle of don’t break trunk it helps to prevent this change from obstructing everyone else’s ongoing work. It also means that once the change has been sufficiently vetted, tested, and corrected, then it will have a single commit where it can be analyzed as a whole. Right now it’s already getting hard to understand the scope of this change and the impacts. For example, in ​PR#10718 there is a change to the .gitignore file, but because it’s a single commit on a chain of changes, the diff view doesn’t show whether the relevant PHP files are still in the .gitignore or not.

I really appreciate the energy going into this to make the Gutenberg sync easier! We still have ample time before 7.0, meaning we should feel no duress to rush hastily. I want this work to continue, but I hope we do so thoughtfully, considerably, and without breaking Core (doing things like skipping security processing by default does not seem to align with those goals either).

Personally I do all my development in a long-running stacked branch which merges multiple in-development branches together, now including a revert of the entire patch-series for this change. I don’t experience any meaningful trouble by maintaining this branch and would be happy to help anyone who is worried about fixing things in a long-running side-branch so that we can have a stable and atomic commit in Core when this change is ready.

I've tested various iterations of this PR throughout the day and thanks to @youknowriad's adjustments was able to get my plugin's unit tests running again.

So, for the common scenario of running unit tests on wordpress-develop, the additional file_exists/class_exists checks are helpful. (Having to run npm commands between checkout and running tests would, in contrast, be ugly, due to the heavily increased built time, storage, etc.)

due to the heavily increased built time, storage, etc.

Just want to note that the built time is actually faster than before.

due to the heavily increased built time, storage, etc.

Just want to note that the built time is actually faster than before.

Oh, this was meant as "increased in comparison to not having to run a build step before" (for plugin unit tests, and similar). :-)

That the build time for when a build is needed/desired is faster is a good side effect, of course!

[peterwilsoncc]

Here's a summary of issues I am seeing (repeating myself so it's all in one comment):

Technical:

• Build now includes 17 package.json files
• Build now includes 172 *.map files, most referencing files that don't exist
• 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
• 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)
• SVN ignore still hasn't been updated
• Per ​GB#74490 (comment) this will require more frequent changes to build tools in WP-Dev

Administratively

• The pull request was only allowed to sit for the holiday period.
• Multiple commits have been made without review approvals
• The initial commit was not tested, the build bug was available in the playground link

I think reverting creating more issues that it solves. This change is necessary for features slated for 7.0 and it's better to solve them way before alpha/beta than run to solve them at the last moment. -- Riad

Let's also see things from the other side a bit: it's a huge change that resolves a ton of friction on the Gutenberg dev side. I can't understate how much work and overhead it is every release to sync and merge the Gutenberg codebase into core. -- Ella

@youknowriad, @ellatrix

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.

I know it's complex to import changes from the Gutenberg repository, this is demonstrating the past friction in updating them. By committing in a broken state, the ease for one set of developers is at the expense of blocking another set of developers.

Blocking, or at least, significantly hindering developers is not worth the cost.

Worth noting that we're in the alpha stage and commits were made swiftly to resolve issues. It's really hard to make these changes without trying them.

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

All of these changes could and SHOULD have been tested in a pull request.

This seems unrelated to how the code is integrated. cc @get_dave for awareness and potential follow-up in Gutenberg.

This is incorrect, the package.json file is changed in ​build-gutenberg.js#L108-L135.

Here’s a pragmatic proposal: what if we introduced a weekly cadence on this one in order to make it easier to find all the places that are broken but without obstructing everything in the meantime?

@dmsnell I largely agree with this but am hesitant about committing then reverting in the event something breaks. The testing can be done on a feature branch so breakages should be detected in the branch on the PR. The actions generate the build, provide a playground link and other means of testing.

I currently have a ​Gutenberg-Build repo that I update each day. I'm happy to do the same for the feature branch so we can test more easily.

[desrosj]

Replying to peterwilsoncc:

Here's a summary of issues I am seeing (repeating myself so it's all in one comment):

Thanks for this summary, @peterwilsoncc. I'm still trying to get up to speed on the changes here and how they work, but this was very helpful to understand the current state of things.

It was also ​flagged today in Slack that the distributed hosting tests appear to be broken as well. There are currently only 3 hosting bots that have reported results in the last 25 commits. It seems the commit prior to [61438] had ​15 unique environments report back, but since then the WP GHA Bot has been the only one consistently reporting.

It seems that the error message described there is the same one that @TobiasBg is seeing above with TablePress.

The hosting tests are mostly a "set it and forget it" type thing that does not require any changes. Depending on how the host is implementing the test runner, they may not pull in updates to the testing script regularly. If changes are required, we will likely need to perform some outreach to the participating hosts with instructions to fix their test reporting.

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

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.

[youknowriad]

Quick update

Build now includes 17 package.json files

This is now solved in the Gutenberg PR addressing the original comments from @peterwilsoncc

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

This is also solved in the latest PR attached to this ticket.

[youknowriad]

In 61476:

Build/Test Tools: Synchronize svn:ignore with .gitignore.

Adds svn:ignore entries for Gutenberg-generated files that were added to .gitignore in [61438].

The following entries were added:

• Root directory: gutenberg
• src/wp-includes: blocks, build, class-wp-block-parser-block.php, class-wp-block-parser-frame.php, theme.json

Props peterwilsoncc.
See #64393.

[wildworks]

In 61472:

General: Restore and deprecate wp_register_development_scripts().

The function was removed in [61438] but should have been deprecated instead of removed outright, per WordPress backward compatibility policy.
Hot reloading is not used anymore in the latest Gutenberg build tool.

Props peterwilsoncc, westonruter.
See #64393.

Indeed, the Gutenberg project may not be using hot reloading, but the @wordpress/scripts library supports the --hot parameter. I believe the --hot parameter no longer works because WordPress core no longer enqueues react-refresh-runtime and react-refresh-entry. Block developers can no longer take advantage of hot reloading unless they add their own code equivalent to the gutenberg_register_vendor_scripts() function.

[youknowriad]

I see, my understanding was that the hot reloading was for core scripts, but I can take a look at wp-scripts based plugins.

[wildworks]

I did a little research and realized that there might not actually be that many plugins that use hot reload.

Search results on WP Directory Searcher: ​https://wpdirectory.net/search/01KEVCJPRYBY8T518FQ70MGK8T

## Summary

Restores the wp_register_development_scripts() function and associated build infrastructure to enable hot module replacement (HMR) when using @wordpress/scripts with the --hot flag.

The React Refresh scripts were removed in [61438] as part of the Gutenberg build restructuring, but they are still needed for plugin developers using wp-scripts start --hot for block development.

## Changes

• Adds react-refresh and @pmmmwh/react-refresh-webpack-plugin npm dependencies
• Creates tools/webpack/development.js to build the development scripts
• Restores wp_register_development_scripts() in script-loader.php
• Removes the deprecated stub from deprecated.php

The scripts are only registered when SCRIPT_DEBUG is true and are not loaded during Core tests.

## Trac Ticket

https://core.trac.wordpress.org/ticket/64393

## Test Plan

1. Set SCRIPT_DEBUG to true in wp-config.php
2. Create a plugin using @wordpress/scripts
3. Run wp-scripts start --hot
4. Verify hot module replacement works when editing React components

🤖 Generated with ​Claude Code

Hot reloading has proven to be not very valuable in Gutenberg and WordPress in general since it's not a typical SPA. That said, this PR restores the previous behavior so we can make an informed decision about whether we still want it or not.

I tested this with an example plugin, it works but I understand why no one really uses this, it's not the seamless experience that you get with SPAs. Anyone, we can see whether to commit or not this PR.

@t-hamano What do you think we should do here? Maybe we can just merge this PR to restore previous status quo even if imperfect.

[SergeyBiryukov]

Replying to TobiasBg:

It looks like this change is also affecting common plugin unit test setups :-(

For example, I'm ​checking out wordpress-develop to have the WP unit test framework available.
However, when running tests I only get

PHP Warning:  require(/home/runner/work/TablePress/TablePress/src/wp-includes/build/routes.php): Failed to open stream: No such file or directory in /home/runner/work/TablePress/TablePress/src/wp-settings.php on line 245
PHP Fatal error:  Uncaught Error: Failed opening required '/home/runner/work/TablePress/TablePress/src/wp-includes/build/routes.php' (include_path='.:/usr/share/php') in /home/runner/work/TablePress/TablePress/src/wp-settings.php:245
Stack trace:
#0 /home/runner/work/TablePress/TablePress/tests/phpunit/includes/install.php(40): require_once()
#1 {main}
  thrown in /home/runner/work/TablePress/TablePress/src/wp-settings.php on line 245

Just came here to report this as well. It appears that unit tests can no longer be run from the src directory in the current state, essentially breaking [50441] / #51734.

[amykamala]

Hi,

I may have missed it if someone already said these things:

The Hosting Team phpunit test runner is failing to report across most configs as of the 5th when this was merged. ​https://github.com/WordPress/phpunit-test-runner/issues/293

The runner is throwing the same error that Sergey mentioned. On my test environment (LAMP) it's this fatal error: PHP Fatal error: Uncaught Error: Failed opening required '/tmp/wp-test-runner/src/wp-includes/build/routes.php' (include_path='.:') in /tmp/wp-test-runner/src/wp-settings.php:245

During the build process the gutenberg-copy task is setting the build target to 'build' which it then is building out routes.php in (in /build) instead of building in /src.

Running "gutenberg-copy" task 🔍 Checking Gutenberg build... Build target: build/ ✅ Gutenberg build found 📦 Copying PHP infrastructure... ✅ routes.php ✅

"Gutenberg copy" task function code:

​https://github.com/WordPress/wordpress-develop/blob/a8924f58aa038fcb892b55fd31d37aeac65c34e5/Gruntfile.js#L1449

const buildDir = grunt.option( 'dev' ) ? 'src' : 'build';

This if else may be returning false and therefore building under 'build'. The statement appears again on line 1466 ​https://github.com/WordPress/wordpress-develop/blob/a8924f58aa038fcb892b55fd31d37aeac65c34e5/Gruntfile.js#L1468 (but I haven't checked this entire file).

[TobiasBg]

@SergeyBiryukov and @amykamala:

If you have a chance, please test ​https://github.com/WordPress/wordpress-develop/pull/10718 for this, which aims at keeping tests working on wordpress-develop.

My thinking is that we should ship this PR to "fix" things for folks using the previous version of wp-scripts but I won't be against removing this entirely from wp-scripts in Gutenberg.

[youknowriad]

In 61487:

Build/Test Tools: Restore React Refresh scripts for hot reloading.

Restores the wp_register_development_scripts() function and associated
build infrastructure to enable hot module replacement (HMR) when using
@wordpress/scripts with the --hot flag.

The React Refresh scripts were removed in [61438] as part of the Gutenberg
build restructuring, but they are still needed for plugin developers using
wp-scripts start --hot for block development.

Props jsnajdr, wildworks, manzoorwanijk.
See #64393.

[youknowriad]

In 61488:

Build/Test Tools: Add missing tools/webpack/development.js

Adds the missing tools/webpack/development.js file that was inadvertently
omitted from [61487].

See #64393.

This was committed.

With the update of the build tool, we also now have prefixed functions, removed the lingering package.json files.

@WordPress/gutenberg-core I'd appreciate a review of this PR. This unblocks folks doing unit tests without building and address all the remaining feedback on the build change. Would be good to land this one.

though I really think we should move the block parser files to core

Agreed :)

[youknowriad]

In 61492:

Build: Improve Gutenberg integration workflow.

This changeset improves the Gutenberg build integration to simplify the developer workflow and reinstore a flow similar to how package dependencies worked before the Gutenberg checkout-and-build approach was introduced.

Key improvements:

• Automatic rebuild on ref change: Adds a new gutenberg:sync script that stores a hash of the built ref in .gutenberg-hash and only rebuilds when the ref changes.
• Full integration on npm install: Running npm install now produces a fully working development environment with Gutenberg assets in src/.
• Clean Gutenberg checkout: Restores Gutenberg's package.json after the build completes.
• Stops copying .js.map files to wp-includes/js/dist since they reference non-existent paths.
• Remove package.json files from the build folder.
• Avoid closures and use prefixed functions.
• Updates build checks to use jquery.js instead of edit-post.js as the build indicator.

Props youknowriad, ellatrix, mcsf, dmsnell, ntsekouras, jorgefilipecosta, tobiasbg, peterwilsoncc.
Fixes #64393.

[manzoorwani.jk]

The sync seems to be broken with the latest Gutenberg trunk (237e6cabddf95ae9e6a5e173d1a0749a89107931) following the changes in ​https://github.com/WordPress/gutenberg/pull/74461 which added block-library/src/navigation-link/shared/helpers.php file.

Steps:

• Update the gutenberg.ref in package.json to 237e6cabddf95ae9e6a5e173d1a0749a89107931
• Run npm install to see the error

📦 Copying blocks...
❌ Unexpected error: Error: ENOTSUP: operation not supported on socket, copyfile 'wordpress-develop/gutenberg/build/scripts/block-library/navigation-link/shared' -> 'wordpress-develop/src/wp-includes/blocks/navigation-link/shared'
    at Object.copyFileSync (node:fs:3085:11)
    at copyBlockAssets (wordpress-develop/tools/gutenberg/copy-gutenberg-build.js:247:9)
    at main (wordpress-develop/tools/gutenberg/copy-gutenberg-build.js:1029:2)
    at Object.<anonymous> (wordpress-develop/tools/gutenberg/copy-gutenberg-build.js:1116:1)
    at Module._compile (node:internal/modules/cjs/loader:1706:14)
    at Object..js (node:internal/modules/cjs/loader:1839:10)
    at Module.load (node:internal/modules/cjs/loader:1441:32)
    at Function._load (node:internal/modules/cjs/loader:1263:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:237:24) {
  errno: -45,
  code: 'ENOTSUP',
  syscall: 'copyfile',
  path: 'wordpress-develop/gutenberg/build/scripts/block-library/navigation-link/shared',
  dest: 'wordpress-develop/src/wp-includes/blocks/navigation-link/shared'
}

Hot reloading doesn't seem to work.

Steps:

1. Run npm run env
2. Run cd src/wp-content/plugins && npx @wordpress/create-block test-block
3. Run cd test-block
4. Run npm run start -- --hot
5. Create a new post and insert a Test Block
6. Make changes to the Edit component of the test-block plugin.
7. Nothing happens in the block editor.

See: ​https://github.com/WordPress/gutenberg/pull/74721#issuecomment-3767450553

Indeed @t-hamano I did test this, so I'm guessing I had some weird setup. I'll push a fix.

## Trac Ticket

https://core.trac.wordpress.org/ticket/64393

## Summary

• Fixes hot reloading (HMR) not working for block plugins when using @wordpress/scripts with the --hot flag
• Root cause: react-refresh-entry.js was bundling its own copy of react-refresh/runtime instead of using window.ReactRefreshRuntime, creating two separate runtime instances
• Fix: Split webpack development config into two configs - one for runtime (creates the global) and one for entry (uses it as external)

## Test plan

1. Create a test block plugin: cd src/wp-content/plugins && npx @wordpress/create-block test-block
2. Activate the plugin
3. Start hot reload: cd src/wp-content/plugins/test-block && npm run start -- --hot
4. Open the block editor and add the Test Block
5. Edit src/edit.js - changes should appear automatically without page refresh

🤖 Generated with ​Claude Code

This should fix it ​https://github.com/WordPress/wordpress-develop/pull/10757