Why Another Wheel?
There are already some Vite packing plugins out there — vite-plugin-zip-pack, vite-plugin-compress, etc. They work, but they always feel like they're missing something. Most of them only support ZIP and offer fairly limited functionality.
In real-world projects, the build packaging step is rarely that simple:
- Multiple compression formats 🗜️ — ZIP for sharing with colleagues, TAR.GZ for deploying to Linux servers, 7Z for higher compression ratio archiving. Different scenarios demand different formats.
- File checksums 🔐 — After packaging, you need MD5/SHA1 checksums to verify version consistency, especially when delivering builds to clients.
- Flexible naming ✏️ — Version numbers, timestamps, hash values — the more information in the filename, the better.
- CI/CD friendly 🚀 — Every build artifact in a pipeline should be uniquely traceable. Auto hash-renaming after compression saves you the hassle of writing scripts to do it manually.
Existing plugins basically can't satisfy all of these at once, which is why I wrote vite-plugin-pack-orchestrator.
What Makes It Different
| Feature | Most Packing Plugins | This Plugin |
|---|---|---|
| Formats | ZIP only | ZIP / TAR / TAR.GZ / 7Z |
| Checksums | None | MD5 / SHA1 / SHA256 |
| File Naming | Fixed name |
[name] [version] [timestamp] [hash] placeholders |
| Hook System | None |
onBeforeBuild / onAfterBuild / onError hooks |
| File Filtering | Partial |
include + exclude glob patterns |
| 7Z Support | Requires system-installed 7z | Bundled, zero dependencies |
| Output Dir | Fixed location | Custom archiveOutDir
|
Installation
npm install vite-plugin-pack-orchestrator -D
Quick Start
The most basic usage — two lines of config and you're done:
// vite.config.ts
import { defineConfig } from 'vite';
import orchestrator from 'vite-plugin-pack-orchestrator';
export default defineConfig({
plugins: [
orchestrator({
pack: {
outDir: 'dist', // Directory to pack, defaults to 'dist'
format: 'zip', // Format: zip | tar | tar.gz | 7z
fileName: 'myapp', // Archive filename
},
}),
],
build: { outDir: 'dist' },
});
Run vite build, and you'll get myapp.zip in your project root.
Configuration Reference
pack — Packaging Options
pack: {
outDir: 'dist', // Source directory (relative to project root), default 'dist'
fileName: 'myapp', // Filename, supports placeholders (see below)
format: 'zip', // Format: 'zip' | 'tar' | 'tar.gz' | '7z'
compressionLevel: 9, // Compression level 0-9, default 9 (maximum)
archiveOutDir: './releases', // Archive output directory, defaults to project root
exclude: ['**/*.map'], // Files to exclude (glob matching)
include: ['**/*.js'], // Files to include (optional, includes all if not set)
}
fileName Placeholders
The filename supports the following placeholders, automatically replaced at build time:
| Placeholder | Description | Example |
|---|---|---|
[name] |
name from package.json |
my-awesome-app |
[version] |
version from package.json |
1.2.0 |
[timestamp] |
Current timestamp | 1714012345678 |
[hash] |
Bundle content MD5 hash (full 32 chars) | a1b2c3d4e5f6... |
[hash:8] |
First N chars of MD5 hash (custom) | a1b2c3d4 |
// Example: fileName = 'release-[version]-[timestamp]'
// Output: release-1.2.0-1714012345678.zip
// Example: fileName = '[name]-v[version]'
// Output: my-awesome-app-v1.2.0.zip
// Example: fileName = '[name]-[hash]'
// Output: my-awesome-app-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.zip
// Example: fileName = '[name]-[hash:8]'
// Output: my-awesome-app-a1b2c3d4.zip
If fileName doesn't include an extension, the plugin automatically appends .zip, .tar.gz, etc. based on the format.
Hooks — Lifecycle Hooks
onBeforeBuild — Before Build
Called before Vite starts bundling. Great for pre-build cleanup:
hooks: {
onBeforeBuild: async () => {
// Pre-build processing
},
}
onBundleGenerated — After Bundle Generation
Called after Vite generates the bundle but before archiving. You can access the build output:
hooks: {
onBundleGenerated: (bundle) => {
console.log('Generated files:', Object.keys(bundle));
},
}
onAfterBuild — After Archive Creation (Core Feature)
This is the most powerful feature of this plugin. After the archive is created, the plugin automatically calculates MD5 / SHA1 / SHA256 checksums and passes them to onAfterBuild. You can use these checksums to rename the archive.
Return a new path (different from the original) and the plugin will automatically rename the file:
hooks: {
onAfterBuild: (path, format, checksums) => {
// path — Full path of the current archive
// format — Archive format ('zip' | 'tar' | 'tar.gz' | '7z')
// checksums — Checksums object: { md5: string, sha1: string, sha256: string }
return path; // Return original path = no rename
},
}
Real-world examples:
// Example 1: Insert SHA1 short hash before extension (most common)
// myapp.zip → myapp-3a7b2c1d.zip
onAfterBuild: (path, format, checksums) =>
path.replace(/(\.(?:zip|tar\.gz|tar|7z))$/, `-${checksums.sha1.slice(0, 8)}$1`);
// Example 2: Replace entire filename with MD5
// myapp.zip → a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.zip
onAfterBuild: (path, format, checksums) =>
path.replace(/^.+(?=\.\w+$)/, checksums.md5);
// Example 3: Append format and hash to original filename
// myapp.zip → myapp-zip-a1b2c3d4.zip
onAfterBuild: (path, format, checksums) =>
path.replace(/(\.\w+)$/, `-${format}-${checksums.sha256.slice(0, 8)}$1`);
// Example 4: Fully custom filename, using format param for extension
// myapp.zip → release-a1b2c3d4e5f6.zip
onAfterBuild: (path, format, checksums) =>
`release-${checksums.md5.slice(0, 12)}.${format}`;
// Example 5: No rename, just use checksums for something else (e.g. write to file)
onAfterBuild: async (path, format, checksums) => {
fs.writeFileSync('checksums.json', JSON.stringify(checksums));
// Not returning or returning original path = no rename
}
onError — On Error
Callback when packaging fails. Great for integrating alert notifications:
hooks: {
onError: async (error) => {
console.error('Packaging failed:', error.message);
// Integrate with Slack / Teams / email alerts here
},
}
Why Auto Hash-Renaming Matters for CI/CD
In continuous integration / continuous deployment pipelines, every build artifact needs to be uniquely traceable. If your archive is always named dist.zip, how do you tell this build apart from the last one? Which version do you grab when rolling back?
This plugin uses the onAfterBuild hook to get checksums and automatically insert a hash into the filename:
hooks: {
onAfterBuild: (path, format, checksums) =>
path.replace(/(\.zip)$/, `-${checksums.sha1.slice(0, 8)}$1`);
}
Build output:
myapp-1.0.2-3a7b2c1d.zip
myapp-1.0.2-7f9e4b2a.zip
The filename itself is the fingerprint 🔑 — you can distinguish different builds at a glance. Deployment scripts can locate versions directly by filename without maintaining a separate version mapping table. Rollback is simple — just find the previous hash filename and deploy it. Combined with [version] and [timestamp] placeholders, traceability is even stronger.
Complete Example
Putting it all together, here's a production-ready configuration:
// vite.config.ts
import { defineConfig } from 'vite';
import orchestrator from 'vite-plugin-pack-orchestrator';
export default defineConfig({
plugins: [
orchestrator({
pack: {
outDir: 'dist', // Pack the dist directory
fileName: 'myapp-[version]', // Filename with version
format: 'zip', // ZIP format
archiveOutDir: './releases', // Output to releases directory
exclude: ['**/*.map'], // Exclude sourcemaps
},
hooks: {
// Auto-append SHA1 hash after compression
onAfterBuild: (path, format, checksums) =>
path.replace(/(\.(?:zip|tar\.gz|tar|7z))$/, `-${checksums.sha1.slice(0, 8)}$1`),
// Log on error
onError: (error) => console.error('Packaging failed:', error.message),
},
}),
],
build: { outDir: 'dist' },
});
One vite build does it all — no extra packaging scripts needed.