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.
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.
- Download WP-CLI & install dist-archive package
- Create a .distignore in your plugin’s root directory
- 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.
