Jonathan Desrosiers 7:03 pm on August 9, 2023  

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

August 8, 2023: Added a reference to the Node.js and npm tutorial on learn.wordpress.org. – @desrosj

As of [56378] in the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase. repository and a3bef32 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 recommended for WordPress development are now 16.x and 8.x, respectively.

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 16.19.1 (the latest is currently (16.20.1). This should also update npm to the correct, expected version appropriately.

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.

Installing Node.js and npm for local WordPress development

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 only Node.js 16?

While it’s true that version 16 is currently in maintenance mode, 18.x is currently not an option due to a systems level constraint. The systems team is working on resolving the blockerblocker A bug which is so severe that it blocks a release., and 16.x is the highest that can currently be used.

What is the blocker?

When a commit is made to develop.svn.wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ (visually represented at core.trac.wordpress.org and mirrored to WordPress/wordpress-develop on GitHub), a private server (known as the build server) checks out the new changeset and executes the build scripts required to create a production ready version of WordPress. The results of this process are then committed to build.svn.wordpress.org (visually represented at build.trac.wordpress.org and mirrored to WordPress/WordPress on GitHub). All WordPress releases are created from this repository.

The version of Node.js specified in the package.json file within wordpress-develop must be available on the build server. If it’s not present, everything breaks. specifics about the WordPress.org infrastructure are kept private and as such the reason behind the blocker will not be disclosed.Until this blocker for installing Node.js >= 18 is resolved, version 16 must be used.

Why not update the Gutenberg repo to version 18 and Core to 16?

This was explored but ultimately ruled out. While it would be nice to use the current active LTS version in the Gutenberg repository, it would make contributing more difficult (contributors would have to also install nvm or know how to change versions on the fly), and potentially introduce some weird edge cases where bugs exist in wordpress-develop and not the Gutenberg pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party/repository.

Why is the EOL for Node.js 16 this September?

When originally placed in maintenance state, version 16.x was set to receive the full 18 months of support (until April of 2024). However, a decision has been made by the Node.js team to bring the EOL date forward by 7 months.

Node.js 16 was originally released with OpenSSL 1.1.1, which is scheduled for EOL on September 11, 2023. To ensure there is no risk of exposure to any vulnerabilities discovered in OpenSSL 1.1.1 between September 2023 and the original EOL date for Node.js 16 of April 2024, the new EOL date for Node.js 16 is now also September 11, 2023.

The systems team is aware of this expedited timeline.

Will version 18 be skipped?

As of the publish date for this post, 18.x is the active LTE version and 20.x is current. Ideally, when the system-level blocker is resolved the jump directly to 20.x can be made. However, it’s not always that easy or straightforward (see the fact that the project used 14.x until today).

This will be evaluated when the time comes and it’s possible 18.x is used as an intermediate step since maintenance for that release is scheduled through April 30, 2025. But, it is becoming more common for packages to set minimum version requirements to the current active LTS. So jumping directly to 20.x could be required after October 2023 (when 20.x becomes active LTS version).

What does updating to 16.x unblock?

There are several dependencies that the editor team has been looking at using to support phase 3 of the project (collaborative editing). However, those dependencies do not support Node.js 14.x. This allows further exploration and experimentation to take place.

The update also opens the door for exploring how to utilize new features in npm, such as workspaces. npm is bundled with Node.js, and the version included is pinned. It’s usually not recommended to update npm independently from Node.js to avoid incompatibilities. So unless Node.js is updated to a version that changes the bundled version of npm, these new features are not reliably available or stable.

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 @youknowriad, @jorbin, @annezazu, and @chanthaboune for reviewing this post.