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. 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. 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 Plugin Directory 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