Conversation
github-actions
bot
added
[Package] Element
|
At #74309 everyone said it should be coordinated with core. Where did this happen? If, with the new Gutenberg integration in core, this requires the core build server to have pnpm, this will break the build server. Apart from that, it puts a burden on contributors to install another package manager and switch between the two for two WP projects. And if we're switching package managers, why not look into alternatives such as Bun? I didn't see any kind of comparison or exploration. That's why coordination is important. A make/core blog post would be a good idea. |
We're not switching package managers just for the sake of it. We're solving a longstanding problem: When these packages are published individually, they're expected to work in isolation. Nobody downloads the entire Gutenberg repo to use the packages—they install them individually. When dependencies aren't properly declared, packages break for downstream consumers. You can see the workarounds/hacks we maintain in Jetpack to handle these issues. Almost every npm works well for end-user applications. For a monorepo that publishes packages consumed by a large community, pnpm is better suited because it enforces strict dependency boundaries—packages can only access dependencies they explicitly declare. This catches missing dependencies during development rather than after publishing. Not just that. The
There are tons of such issues that we have to deal with just because of using npm
Core doesn't face this problem because it doesn't publish packages to npm. It doesn't need to switch, but if we want to have pnpm there as well, I will be more than happy to lead the effort. For Core, the switch should be much easier than Gutenberg.
The published packages can be installed with any package manager—npm, pnpm, yarn, or bun. The pnpm requirement only applies to developing within the Gutenberg monorepo itself. I'm not fully aware of how Core's build process works regarding Gutenberg integration, but if there are specific concerns, I'd appreciate more details so we can address them.
That's a fair point. However, pnpm offers tangible benefits for contributors too: faster installs, reduced disk space usage (through content-addressable storage), and better error messages when dependencies are misconfigured. Modern Node.js also ships with Corepack, which makes pnpm available without a separate global install ( The learning curve is minimal since pnpm commands mirror npm (
Bun is more than a package manager—it's an entirely different JavaScript runtime that replaces Node.js. Adopting Bun would mean testing all of Gutenberg's tooling against a different runtime, which is a much larger change with higher risk. pnpm is a focused change: same Node.js runtime, different package manager. It's also mature and battle-tested, used by major projects like Vue, Vite, and Astro. If Bun matures further and the community decides it's worth exploring, migrating from pnpm to Bun would actually be simpler than migrating from npm (the dependency resolution models are more similar). If npm would provide an option to not hoist dependencies, then we would not have the need for this change. |
I agree with all your points.
This can be done in Core pretty easily. Switching to pnpm is Core can be technically done in a glimpse. The only problem is that this not only affects Core but also a ton of other packages, like themes and even performance.
I don't really find problematic the fact GB leads the change to |
Core doesn't use the packages anymore, it clones the Gutenberg repo directly. See https://core.trac.wordpress.org/ticket/64393 That's why this is a real concern and why coordination is important.
You can use Bun just for package management without using the rest of it, FWIW. |
Thank you for sharing that. Looking at the Gutenberg sync here, it is run in isolation there, which is good and should be pretty easy to replace that installation command with I see that some people are not happy with the way sync works - taking a couple of gigs of disk space, and a lot of time. This is even a stronger case for pnpm as the dependencies are symlinked from a central store, with not much disk space utilized inside the Core repo, and also being faster than I did a little benchmark test to check the time taken by Gutenberg sync/clone to install the deps
You can see the stark difference in speed, although the results may vary based on where in the world you are. Here are all the changes I had to make in Core to make it workdiff --git a/package.json b/package.json
index a5d54d773e..0c184f3074 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,7 @@
"url": "https://develop.svn.wordpress.org/trunk"
},
"gutenberg": {
- "ref": "7bf80ea84eb8b62eceb1bb3fe82e42163673ca79"
+ "ref": "update/switch-to-pnpm"
},
"engines": {
"node": ">=20.10.0",
diff --git a/tools/gutenberg/build-gutenberg.js b/tools/gutenberg/build-gutenberg.js
index cf6dd97395..9c1a208e93 100644
--- a/tools/gutenberg/build-gutenberg.js
+++ b/tools/gutenberg/build-gutenberg.js
@@ -148,7 +148,7 @@ async function main() {
? '--base-url="includes_url( \'build\' )"'
: "--base-url=includes_url( 'build' )";
- await exec( 'npm', [ 'run', 'build', '--', '--fast', baseUrlArg ], {
+ await exec( 'pnpm', [ 'run', 'build', '--skip-types', baseUrlArg ], {
cwd: gutenbergDir,
} );
diff --git a/tools/gutenberg/checkout-gutenberg.js b/tools/gutenberg/checkout-gutenberg.js
index 42e35a1967..0413175472 100644
--- a/tools/gutenberg/checkout-gutenberg.js
+++ b/tools/gutenberg/checkout-gutenberg.js
@@ -222,7 +222,7 @@ async function main() {
}
try {
- await exec( 'npm', [ 'ci' ], { cwd: gutenbergDir } );
+ await exec( 'pnpm', [ 'install', '--frozen-lockfile' ], { cwd: gutenbergDir } );
console.log( '✅ Dependencies installed' );
} catch ( error ) {
console.error( '❌ npm ci failed:', error.message ); |
||||||||||
|
Still, it's crucial that the build server has pnpm installed first. Otherwise builds will break. |
That's true, but it's easy to enable via NodeJS Corepack. corepack enable pnpm |
ntwb
left a comment
ntwb
left a comment
There was a problem hiding this comment.
Placeholder comment, details to follow
|
I am doing some research about the issues npm has been causing us, and I will share the results here. |
Well, only dependencies they explicitly declare and anything directly depended on by the monorepo root (or any other parent directory of the package, if you have nested packages). That's why in Jetpack we keep as few dependencies in the monorepo root as possible, with a lot of things shunted into a utility workspace (
Looks like they removed corepack from the nodejs distribution for Node 25. |
Yes, once we adopt pnpm, then we can move the pieces to workspaces just as I did for Storybook in #74640
TIL. |
Research reportI did a little research and found 60+ issues spanning 6 years - all stemming from the same root cause: npm hoists dependencies to the root, so packages can import things they never declared. Everything works fine in the monorepo, but breaks for anyone installing the published packages individually. With pnpm, we'd catch these at development time instead of hearing about them from frustrated developers after a release. If this list doesn't make the case for stricter dependency management, I'm not sure what would. Missing Dependencies on
|
|
Flaky tests detected in e2f1786. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/21978733298
|
There was a problem hiding this comment.
Thanks for all of the time and effort put into the pull request and research here. In addition to the questions and suggestions I added contextually to the PR, I just wanted to chime in here with a few thoughts and some questions.
I’ve seen a number of statements that run contrary to this, so I want to remind everyone that Gutenberg = Core and Core = Gutenberg. Even though there’s two code bases, it’s the same team and everyone should work together. Using one code base to make changes and expecting the other to follow is not the right way to approach changes, especially ones affecting long-used foundational tools. Everyone should work together at all points of the process to avoid unforeseen complications or breakdowns.
I’ll also echo what @swissspidy and @youknowriad have said a bit more directly. This change cannot happen without a proposal posted on the Make WordPress Core blog that allows time for a consensus to be reached and confirmed for a number of reasons that I’ll explain below.
The first reason is that the overwhelming majority of people do not monitor every new pull request opened on this repository. While there are 24 contributors tagged for review, we need to make sure we seek feedback from everyone, not just those who are currently active within this part of the code base. There are currently 6,600+ subscribers to the Make WordPress Core blog, so a post there casts a much wider net and can produce some quality feedback. We don’t know what we don’t know, and we can’t discover what we don’t know unless we actively seek it out.
Proposals are not just about whether a given change is a good thing, though it is a good way to stress test or strengthen the consensus that the suggested changes are beneficial to make. They’re also about gathering valuable feedback from the broader community, especially those with deep historical knowledge and context. They are about research, awareness, collaboration, communication, planning, and ensuring everything goes as smoothly as possible. Does a proposal slow the process down? Yes. But taking the time to pursue higher quality outcomes is worth the delay.
It’s likely that some of the problems caused by the recent changes to the build script could have been avoided had a proposal been published. I’m not looking to revisit that as we should focus instead on moving forward by working together to fix any outstanding issues. But I think we can take this opportunity to try and avoid similar issues with this proposed change.
I also have a few outstanding questions that I don’t see explored.
First, I don’t see any discussion around how this impacts the Security Team’s ability to ship patches for reported security vulnerabilities. The project currently ships security patches all the way back to version 4.7 (which includes every version of WP that includes the block editor). When vulnerabilities need to be patched within the block editor code maintained in this repo, the changes are merged into the respective wp/X.Y branches before publishing bug fix releases to npm and then bumping the package versions in the corresponding branches in wordpress-develop.
How does this change affect this process? The amount of work required to backport this tooling change through 5.0 is likely significant and not a worthwhile use of contributor resources. So the workflows that publish to npm must be tested to ensure this works as expected. I'm also unclear as to whether the actual patches applied to fix an issue in older branches would end up being different depending on the tool being used. It also means that members of the Security Team will need to use both npm and pnpm and know which commands to use based on which branch they are on. In my opinion, this added friction could be a strong argument for continuing to use npm for the sake of consistent tooling across all branches of WordPress.
Another thing I do not see discussed is how this impacts the distributed hosting tests. These test reports are submitted by hosts running the phpunit-test-runner, which is a script that checks out wordpress-develop, runs the build script to prepare WordPress, and runs the PHPunit test suite before reporting the results back to wordpress.org. It’s currently still broken for many of the participants as a side effect of the previous build script changes.
If the project switches to pnpm, every participant must update their host test servers to ensure that pnpm is present, otherwise their test runner will fail. This tool is not easy to update because the tool is meant to be “set it and forget it”. There would need to be a coordinated effort with the hosting team combined with direct outreach to every participant to make sure they are aware of the changes. Just like ensuring PNPM is installed on the build server before committing to work as core, this should be done before committing the change to avoid interruptions in this feedback loop, which has caught critical problems in specific changes to WordPress Core in the past.
As for the proposal to use pnpm itself, my main concern aside from the unanswered questions above is the timing. I’m currently of the opinion that merging this change now would be very poorly timed. There are still a handful of bugs being investigated with the previous changes to the build script in wordpress-develop. Making a change to the underlying tools used for the build script would introduce another large variable into that equation and potentially make it even harder to investigate the unresolved fixed bugs. We should focus efforts on reaching a more stable and confident state there before making this change.
I think it’s also preferable to not make this change in the weeks leading up to beta 1. With just 4 weeks remaining until 7.0 beta 1 (19 February), changes that require contributors to make adjustments to their workflow could be a distraction that takes up valuable time that would have otherwise been spent on feature work.
One last thing I’m not 100% clear on is which problems are solved by using pnpm for the package publishing process vs. which problems are solved by using pnpm as the package manager during development vs. which problems are solved when both are true. For example, would using pnpm solely for publishing solve the majority of the problems without requiring contributors to install and make use of it locally?
Thanks again for all the hard work here! I look forward to the proposal post on the Core blog so that any feedback offered by contributors with opinions or relevant experience can be considered to make the case for this proposed change a stronger and more compelling one and everyone can work together to ensure it's successful.
| "packageManager": "pnpm@10.27.0", | ||
| "engines": { | ||
| "node": ">=20.10.0", | ||
| "npm": ">=10.2.3" |
There was a problem hiding this comment.
Is there any reason why this cannot remain during the transition period? I guess it would prevent someone from only having pnpm installed since engine-strict=true? 🤔
Since 10.2.3 is the version of npm bundled with Node.js 20.10.0, someone should meet this criteria in almost every situation, though. I'll admit that I'm not sure whether it's common for someone to remove npm after installing Node.js, though.
package.json
Outdated
| "@playwright/test": "1.57.0", | ||
| "@testing-library/dom": "^9.3.4", | ||
| "@testing-library/jest-dom": "^6.6.3", | ||
| "@testing-library/react": "14.3.0", |
There was a problem hiding this comment.
Could you explain the rationale behind adding version qualifiers here? Is this necessary for the current changes? Does this result in inconsistencies locally for contributors running install or related commands?
I'm not aware of a discussion around this. If the goal is to move away from using pinned versions, that should be discussed and implemented wholesale instead of piecemeal. I'm unclear on when a version constraint is used and why as the file stands today. Just want to make sure these are intentional.
| VERSION: ${{ steps.get_version.outputs.new_version }} | ||
| run: | | ||
| git add gutenberg.php package.json package-lock.json | ||
| git add gutenberg.php package.json |
There was a problem hiding this comment.
Will changes to the pnpm-lock.yaml file ever need to be committed?
| show-progress: ${{ runner.debug == '1' && 'true' || 'false' }} | ||
| persist-credentials: false | ||
|
|
||
| - name: Install pnpm |
There was a problem hiding this comment.
Does this need to happen after configuring the desired version of Node.js to ensure it's installed & configured correctly?
Running it prior would result in the default version of Node.js on the Actions runner being used instead when installing, which could be problematic in some scenarios.
| git config user.name "Gutenberg Repository Automation" | ||
| git config user.email gutenberg@wordpress.org | ||
|
|
||
| - name: Install pnpm |
There was a problem hiding this comment.
Same question here. Should this happen after setting up Node.js?
| node-version-file: 'main/.nvmrc' | ||
| registry-url: 'https://registry.npmjs.org' | ||
| check-latest: true | ||
| cache: pnpm |
There was a problem hiding this comment.
When building production assets, caches should never be used to avoid cache poisoning.
package.json
Outdated
| "bugs": { | ||
| "url": "https://github.com/WordPress/gutenberg/issues" | ||
| }, | ||
| "packageManager": "pnpm@10.27.0", |
There was a problem hiding this comment.
My understanding of packageManager is that this specific version of pnpm will be enforced. This would require constant bumping to allow contributors to make use of newer versions.
Because engines-strict is set to true, can the version be removed here in favor of engines.pnpm?
| node-version-file: '.nvmrc' | ||
| check-latest: true | ||
| cache: npm | ||
| package-manager-cache: true |
There was a problem hiding this comment.
Looking at the documentation, this is what it says for package-manager-cache:
Controls automatic caching for npm. By default, caching for npm is enabled if either the devEngines.packageManager field or the top-level packageManager field in package.json specifies npm and no explicit cache input is provided.
The description makes it seem that this only controls caching for npm? I don't see any indication in the Action logs that it successfully detected pnpm and configured caching accorrdingly. It's possible that just cache: pnpm is required.
| run: npm run build -- --skip-types | ||
| - name: Detect package manager | ||
| id: detect-pm | ||
| run: | |
There was a problem hiding this comment.
I'm wondering if there is a way to handle this with a command instead of having to detect this within Action files.
If not, then this should be abstracted into a separate job and the output should be shared with every other job in the workflow instead of having to run it twice.
There was a problem hiding this comment.
Also, I know that the goal here was to ensure a smooth transition.
But if there is a proposal published and a schedule announced after, everyone would be made aware of the change and the only impact should be that the GitHub Action workflows for each pull request would no longer pass. Wouldn't rebasing or updating the HEAD branch fix that?
I'm leaning towards not including this at all if we can help it. It could help contributors with the transition. But on the other hand, it could temporarily be a blocker for some.
| @@ -49,10 +49,10 @@ jobs: | |||
| with: | |||
There was a problem hiding this comment.
Both React Native workflows are currently disabled. I lean towards not making changes to these files because they currently cannot be tested.
I have been meaning to open an issue that suggests we should remove the RN-specific dependencies and workflows until there is a coordinated effort to support this going forward. They can always be restored through version control in the future.
|
We can address the code review separately. I just wanted to mention that I am working on a Make Core proposal for this, to discuss it further. Meanwhile, I will try to keep this branch up to date. |
|
Thank you, @desrosj, for a thorough review and response. I really appreciate it. FYI, I am already working on a Make Core proposal and would appreciate your review before publishing it. I will try to reach out via Core Slack. |
6 participants
What?
Closes #74309, supercedes #74135.
Switch the package manager from npm to pnpm.
Why?
How?
The CI and build scripts are updated to auto-detect the package manager, allowing performance comparisons between npm-based trunk and pnpm branches during the transition.
Key changes for smooth transition
.github/setup-node/action.yml
pnpm-lock.yamlvspackage-lock.json)bin/plugin/commands/performance.js
With some help from Claude Code:
detectPackageManager()to detect npm/pnpm based on lock filegetInstallBuildCommand()andgetRunCommand()helpers that use the correct package managerOther notable changes
"optional": truediff noise (npm/npm#17722) since pnpm doesn't have this issuenode_modules/.pnpmstructure when patching podspec files@terrazzo/parser(required due to stricter module resolution)Preparatory PRs
These PRs were created in advance to ease the transition:
skipDefaultLibCheckwithskipLibCheck#74239Single commit approach
This PR uses a single squashed commit to make rebasing easier when keeping the branch up to date with trunk. For the full iteration history, see the exploration PR #74135.
Testing Instructions
pnpm installpnpm run buildpnpm test:unitNext steps
npm runscripts (which still work but should use pnpm)test/directory. This is because the packages can access only dependencies they explicitly declare and anything directly depended on by the monorepo root (or any other parent directory of the package, if you have nested packages). Thus we will need to clean up the root package.json and not have any unnecessary dependencies there.minimumReleaseAgeto prevent supply chain attacks)