Updating WordPress to use more modern versions of Node.js/npm: Part 2

As of [57212] in the wordpress-develop SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase. repository and 415ecc9 in the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ repository, the versions of Node.js and npm required for WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. development are now 20.x and 10.x.

Required action by contributors

In order to continue contributing to WordPress through wordpress-develop or WordPress/Gutenberg, you’ll need to upgrade the version of Node.js installed on your machine to one that’s greater than or equal to 20.10.0 (currently the most recent generally available version 20.x version). This should also update npm to the correct, expected version appropriately (10.2.3 or higher is required).

Using nvm (Node Version Manager) is the recommended and most common way to change the version of Node.js you are running. Both wordpress-develop and the Gutenberg repositories have an .nvmrc file specifying the desired version. Running nvm install within your checkout’s directory will automatically install the latest version that falls within the defined constraints.

If you need further guidance on how to install or use Node.js, npm, or nvm, there is a great tutorial explaining in great detail on learn.wordpress.org.

Note: If you have any open pull requests, you will likely need to update your branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". to include these changes to ensure they work and are tested properly.

How does Node.js versioning work?

Before diving in to some of the background for this change, here is a brief overview of how the versioning for Node.js releases works:

  • Excluding the main branch (which is always considered unstable), there are 3 states for versions: current, active (LTS or long term support), and maintenance.
  • Major versions (18.x, 19.x, etc.) are released every April and October.
  • October releases (always odd numbered) have a support life of 8 months: 6 in current state, 2 in maintenance. They enter maintenance state in April when the next major version is published.
  • April releases (always even numbered) are converted to active LTS in October after 6 months as the the current version. They remain in active LTS state for 12 months before moving to maintenance for 18 additional months.

You can read more about this on the project’s Releases page, or the project’s README file on GitHub.

Why Node.js 20 and not 18 or 21?

While it’s always the preference to use the latest version of any software, that’s not always feasible. When upgrading, the team always looks to upgrade to the newest possible version at the time. Initially 18.x was targeted for the next update. However, version 20.x is now the current active LTS version. While 18.x is still in maintenance mode and will not reach end of life (EOL) until April of 2025, 20.x will not reach EOL until April 2026. Testing revealed that there were no blockers for updating to 20.x, so this was determined to be the best landing spot at this time.

While it’s true that 21.x is newer and the current version of Node.js, 20.x is the current active LTS version. Because odd versions of Node.js are only supported for 8 months, the project does not typically utilize them.

Can I use Node.js 21 if I want?

Yes! You are free to use any version of Node.js over 20.10.0. But 20.x will always be used to perform any official processing and building of the two projects.

However, the Gutenberg repository will now run some tests against newer versions of Node.js as they become available with the hope that problems can be caught earlier, reducing the level of effort required to update Node.js version requirements in the future.

If you discover a problem working with the wordpress-develop or gutenberg repositories on Node.js 21.x, please open a ticketticket Created for both bug reports and feature development on the bug tracker. in the appropriate location so it can be investigated.

How does this work? There is an upper limit defined for the npm version.

The upper limit for the npm version allowed has been removed. This was previously in place because a new format for the package-lock.json file was introduced in npm 7. While the new and old formats were both forward and backward compatible, running npm install using 6 and 7 caused the format to change back and forth. There are currently no known issues that would cause similar problems, so the limit has been removed to allow contributors to use Node.js 21.x if desired, and allow for testing newer versions.

If new compatibility issues are discovered, adding a new upper limit can be explored at that time.

What about the other branches of WordPress Core?

The version of Node.js used by all branches of WordPress is currently 14.x with two exceptions: trunk and 6.4. Before today, both were using 16.x. To limit the number of different versions used throughout Core, the 6.4 branch has also been updated to use 20.x.

As a reminder, only the most recent version of WordPress is actively supported (currently 6.4.x).

Though security patches are occasionally backported to WordPress 4.1.x, this is not guaranteed and is only done as a courtesy. The build tools in these older branches were recently updated to be more consistent and reliable. The level of effort to update, test, and commit the changes required to support Node.js 20.x to all 24+ branches that can potentially receive a security update is very high and is not a good use of time until it’s absolutely necessary.

Because of this, there are currently no plans to update older branches to use Node.js 20.x at this time.

Will the required version be updated to 22.x when it’s released in April 2024?

Maybe. This will be evaluated to determine if the update makes sense for the project when the time comes.

Where can I learn more?

Here is a list of locations where discussions related to these changes took place:

This change will likely require some documentation and handbook updates. If you notice any adjustments that need to be made, please do point them out in the appropriate locations so that they can be corrected!

Props @jorbin for pre-publish review.