This week, I’m going to walk you through setting up WP-CLI’s dist-archive so you can easily zip up new versions of your plugin.

Over the last year, I’ve built a handful of plugins that need to be run through manual testing before new versions are officially released.

Typically I would manually “right-click” and “compress” the folder on my mac, then hand it over to whoever was manually testing the updated version.

This process didn’t take long, but was error-prone and regularly caused confusion.

Unfortunately, I’ve seen several production plugins in the WordPress plugin repository that include files that should never be included in the production zip:

• testing files
• developer dependencies
• scripts

​

Most developers don’t take time to define their plugin packaging process

Its easier to make mistakes when your process isn’t defined:

• The manual process is hard to replicate
• The plugin test suite is accidentally included
• Improper compression breaks existing installs
• Assets include both minimized and the full uncompressed source

All of these issues can be resolved by using WP-CLI’s tool: dist-archive

Here’s how to use it in 3 easy steps:

Step 1: Install WP-CLI and the dist-archive package

WP-CLI is a great tool because it allows you to interact with WordPress through the command line.

You’ll either need a local environment capable of running WP-CLI, or have it installed globally.

When you have WP-CLI installed, you also need to install the dist-archive plugin because it’s not included by default.

Run this command to install it:

wp package install wp-cli/dist-archive-command

You can verify that it’s installed by using the command without any arguments and WP-CLI will output the usage instructions for you:

wp dist-archive

Now you’re ready to create production-ready versions of your plugins.

Step 2: Create a .distignore file

Many developer tools support using a .distignore to identify which files to exclude when performing an action.

WP-CLI also supports this with dist-archive so you can define which files should be excluded from the final plugin ZIP.

You can define the files to exclude once and never worry about it again.

The .distignore works just like your .gitignore—assuming you are using version control. Include it in the root of your plugin.

Here’s an example of what you might put in your .distignore:

Here’s a Github gist that you can copy directly into your plugin. Be sure to edit the list of files specific to your plugin.

Step 3: Compress your plugin and distribute

Now that you have the dist-archive package installed and a .distignore to define files to exclude, you are ready to create a production-ready zip of your WordPress plugin.

As an example, let’s say that I’m working on a newer version of Hello Dolly and this is my main plugin file:

dist-archive will extract the plugin’s current version in the zip file it creates. To zip up this example, I’ll run the dist-archive command and get verification when it finishes zipping it up:

Notice that the created zip also has the plugin version embedded. This helps identify what version of the plugin the zip contains.

Now you can share this zip with anyone who needs to test your plugin, beta test users, or anyone that wants to install it on their site.

You can even use this in a github action to make the process even easier.

I’ve been using @wpcli to rapidly package plugins for testing:

1. Tag new release on Github
2. GH Action runs dist-archive
3. Plugin zip is attached to current release
4. Drop plugin into a fresh WP Install
5. Test Functionality

Pre-releases also help (1.2.3-rc.01)

— Tanner Record (@tarecord) February 28, 2023

In Review

WP-CLI’s dist-archive package has what you need to zip up production ready versions of your plugin with a single command.

1. Download WP-CLI & install dist-archive package
2. Create a .distignore in your plugin’s root directory
3. Run dist-archive to create your production ready distribution

I hope this inspires you to add this tool to your project so you can use a standard process for producing plugin zips.