WordPress packages publish to npm every two weeks

This is a follow-up update to the post from last year: Publishing WordPress packages to npm. It’s worth reminding that we maintain a collection of over 80 npm packages under the WordPress organization.

TLDR; We made WordPress packages publishing to npm more predictable by synchronizing it with bi-weekly 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/ 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 RC1 release. We no longer have to keep the process tightly coupled with WordPress major releases.

Revised branching strategy for npm publishing

The Gutenberg repository still follows the WordPress SVN repository’s branching strategy for every major WordPress release. In addition to that, there are two other special branches that control npm publishing workflows and they are used as follows:

  • The wp/latest 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". contains the same version of packages as those published to npm with the latest distribution tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.). The goal here is to have this branch synchronized with the last Gutenberg plugin release, and the only exception would be unplanned Standalone Bugfix Package Releases (read more below).
  • The wp/next branch contains the same version of packages as those published to npm with the next distribution tag. It always gets synchronized with the trunk branch. Projects should use those packages for development or testing purposes only.
  • A Gutenberg branch wp/* (example wp/6.0) targeting a specific WordPress major releasemajor release A release, identified by the first two numbers (3.6), which is the focus of a full release cycle and feature development. WordPress uses decimaling count for major release versions, so 2.8, 2.9, 3.0, and 3.1 are sequential and comparable in scope. (including its further minor increments) gets created based on the wp/latest Gutenberg branch just after the last Gutenberg release planned for inclusion in the next major WordPress release.

Release types and their schedule:

  • Synchronizing Gutenberg Plugin (latest dist tag) – publishing happens automatically every two weeks based on the newly created release/* (example release/12.8) branch with the RC1 version of the Gutenberg plugin.
  • WordPress Releases (patch dist tag) – publishing gets triggered manually from the wp/* (example wp/6.0) branch. Once we reach the point in the WordPress major release cycle (usually after BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 1) where we only cherry-pick commits from the Gutenberg repository to the WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., we use wp/* branch (created from wp/latest) for npm publishing with the patch dist-tag. It’s also possible to use older branches to backportbackport A port is when code from one branch (or trunk) is merged into another branch or trunk. Some changes in WordPress point releases are the result of backporting code from trunk to the release branch. bugs or security fixes to the corresponding older versions of WordPress Core.
  • Development Releases (next dist tag) – it is also possible to perform development releases at any time when there is a need to test the upcoming changes.

There is also an option to perform Standalone Bugfix Package Releases at will. It should be reserved only for critical bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes or security releases that must be published to npm outside of regular cycles.

The complete documentation is available in the BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor Handbook.

Running npm publishing with GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ workflows

While the npm publishing got configured to happen automatically every two weeks as part of the Gutenberg plugin release workflow, there might still be cases when other release types need to be executed. To start the process, go to Gutenberg’s GitHub repository’s Actions tab, and locate the “Publish npm packages” action. Note the blue banner that says “This workflow has a workflow_dispatch event trigger.”, and expand the “Run workflow” dropdown on its right-hand side.

There are three ways to publish packages to npm depending on the their type:

  • WordPress major release – select wp from the “Release type” dropdown and enter X.Y (example 5.9) in the “WordPress major release” input field.
  • Development release – select development from the “Release type” dropdown and leave “WordPress major release” input field empty.
  • Bugix release – select bugfix from the “Release type” dropdown and leave “WordPress major release” input field empty.

Finally, press the green “Run workflow” button. It triggers the npm publishing job, which needs then to be approved by a Gutenberg Core team member.

Testing JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. code from a specific major WordPress version

An interesting bonus got included with the revised workflow for npm publishing related to WordPress major releases. It’s now possible to quickly install a version of the individual WordPress package used with a given WordPress version using distribution tags (example for WordPress 5.8.x):

npm install @wordpress/block-editor@wp-5.8

It’s also possible to update all WordPress packages in the project with a single command:

npx @wordpress/scripts packages-update --dist-tag=wp-5.8

There is support for switching WordPress packages to versions that fully align with the following major WordPress versions: 5.7, 5.8, 5.9 and 6.0.


Thank you to @annezazu and @priethor for their feedback shared while compiling this post.

#core-js, #javascript, #npm-packages

Publishing WordPress packages to npm

The WordPress project has started publishing its packages to npm – the largest package repository – over 4 years ago. As of today, there is a collection of nearly 80 actively maintained packages under the WordPress organization.

The latest updates to the process were documented on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ in PR#29028. I wanted to share some details about the latest addition to the process and summarize the overall strategy for publishing.

Development releases

WordPress trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. can be closed or in “feature-freeze” mode. Usually, this happens during the WordPress ongoing release cycle (like now with WordPress 5.7), which takes several weeks. It means that packages don’t get any enhancements and new features during the ongoing WordPress major releasemajor release A release, identified by the first two numbers (3.6), which is the focus of a full release cycle and feature development. WordPress uses decimaling count for major release versions, so 2.8, 2.9, 3.0, and 3.1 are sequential and comparable in scope. process.

Another type of release was introduced to address the limitation mentioned earlier and unblock ongoing development for projects that depend on WordPress packages. It takes advantage of package distribution tags that make it possible to consume the future version of the codebase according to npm guidelines:

By default, the latest tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) is used by npm to identify the current version of a package, and npm install <pkg> (without any @<version> or @<tag> specifier) installs the latest tag. Typically, projects only use the latest tag for stable release versions, and use other tags for unstable versions such as prereleases.

npm documentation

In this case, the next distribution tag is used for publishing the devolvement version of the packages. Developers can install a package in their project by typing:

npm install @wordpress/components@next

The release process is fully automated via a single command:

 ./bin/plugin/cli.js npm-next

The person in charge of the release needs only to run the script, and everything else happens through interactions in the terminal.

Behind the scenes, the wp/next 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". is synchronized with the latest release branch (release/*) created for 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/ 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. To avoid collisions in the versioning of packages, we always include the newest commit’s sha, for example, @wordpress/block-editor@5.2.10-next.645224df70.0.

Release types and their schedule

It’s worth clarifying that the Gutenberg plugin consumes the local copy of WordPress packages because they are developed inside the same repository. It’s a completely different story for the WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. that consumes the packages from the npm registry.

The following list includes the full list of supported release types for publishing WordPress packages to npm:

  • Synchronizing WordPress Trunk (latest dist tag) – when there is no “feature-freeze” mode in WordPress Core, then publishing happens every two weeks based on the new stable version of the Gutenberg plugin. Otherwise, only bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes get manually included and published to npm before every next betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. and RCrelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta). version of the following WordPress release. There is a script that automates the process: ./bin/commander.js npm-latest.
  • Minor WordPress Releases (patch dist tag) – only when bug fixes or security releases need to be backported into WordPress Core. It’s a manual process that requires cherry-picking individual commits and ends with executing npm run publish:patch command.
  • Development Releases (next dist tag) – at least every two weeks when the RC version for the Gutenberg plugin is released. There is a script that automates the process: ./bin/commander.js npm-next.

There is also an option to perform Standalone Package Releases at will. It should be reserved only for critical bug fixes or security releases that must be published to npm outside of a regular WordPress release cycle. It’s a manual process with many steps required that ends with executing npm run publish:prod command.


We are constantly seeking feedback to improve the processes around npm packages. The workflow for the WordPress core works quite well, and we didn’t discover any major issues when backporting the changes applied to the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor in the Gutenberg plugin. Let us know what else we can do to improve the experience for projects that consume WordPress packages from npm.

#core-js, #javascript, #npm-packages