wp-release

Build, verify, version and deploy WordPress plugin and theme releases from one CLI, a library or GitHub Actions.

Open as Markdown

Releasing a WordPress plugin means a ZIP with the right root folder, the same version in several places, a changelog and, for WordPress.org, an SVN commit. wp-release does each of them with one command.

npx @wpelevator/wp-release zip
npx @wpelevator/wp-release version-check
npx @wpelevator/wp-release verify --zip my-plugin.1.4.2.zip --checksums my-plugin.1.4.2.checksums.json
/home/me/my-plugin/my-plugin.1.4.2.zip
All versions match 1.4.2.
4 files match, 0 changed, 0 missing and 0 extra.

That is the output for a plugin whose readme Stable tag matches its Version header, and a checksums manifest built with zip --checksums. The quickstart runs each step and shows what a mismatch looks like.

No config file is needed to start. Try it on your plugin in a minute.

What you get

  • A ZIP that WordPress.org accepts. It has the {slug}/ root folder, leaves out what .distignore lists, and the same files give the same ZIP. It is built in Node.js, with no zip binary. Build a release ZIP.
  • Version mismatches caught before release. version-check compares the Version header with the readme Stable tag, and with PHP constants and the git tag when you ask. Check versions.
  • Proof that a release wasn't tampered with. Checksums list every file, and verify names each file that was added or changed. Ed25519, minisign and SSH signatures cover the ZIP and the manifest. Verify and sign.
  • Releases from pull requests. Changesets turn notes in each pull request into version bumps, changelogs and tags, for one plugin or a monorepo. Release from GitHub Actions.
  • One-command deploys. Deploy to WordPress.org or to a Git repository, with --dry-run to see the changes first.
  • Translations. Extract a POT file and compile PO files to MO, JSON and PHP.

Pick your path

I want to Start here
Build a release ZIP and check it Quickstart
Automate versions, changelogs and tags Release from GitHub Actions
Publish to WordPress.org Deploy to WordPress.org
Prove a release is unchanged Build, verify and sign
Release many packages from one repository Release a monorepo
Run commands in a workflow Use it in GitHub Actions
Call it from Node.js Library API

WordPress.org themes are released by uploading a ZIP, so deploy svn is for plugins only. Use zip to build a theme upload.

Projects without Node.js can use PHP Changesets (wpelevator/php-changesets), which runs the same changeset workflow with PHP and Git alone.

Install

Run commands with npx as above, or add the package to your project:

npm install --save-dev @wpelevator/wp-release

Node.js 22.12 or later is required. SVN deployments also need the svn command line client. Git deployments and changeset commands need Git.

The package is an ES module with TypeScript declarations. CommonJS projects can load it with require( '@wpelevator/wp-release' ) on Node.js 22.12 or later.

Zero-install examples in these docs use npx @wpelevator/wp-release, because npx wp-release alone runs an unrelated npm package until this one is installed. After npm install, npx wp-release and wp-release in npm scripts are the same command.

Reference