vite-plugin-pack-orchestrator，One Vite Plugin for Compression, Checksums, and Auto Hash-Renaming

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' },
});