vite-plugin-archiver

0.3.2 verified Mon Apr 27 auth: no javascript

A Vite plugin that archives the build output into a ZIP or TAR file after a successful build. Current stable version 0.3.2, released sporadically with no fixed cadence. Only supports ESM imports. Key differentiator: integrates deeply with Vite's build lifecycle and uses archiver.js for archive creation, with options for output type, compression level, filename templates (using dayjs), and auto-open of archive directory. Requires Vite 6/7/8. Ships TypeScript types. Lightweight with no other runtime dependencies.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module ↓

cause Using CommonJS require() to load the plugin in a CJS project.

fix

Switch to import syntax or set "type": "module" in package.json. If using TypeScript, ensure esModuleInterop is enabled.

error TypeError: ArchiverPlugin is not a function ↓

cause Default import assumed the plugin is an object with a 'plugin' property, but the module exports a function directly.

fix

Use ArchiverPlugin directly as a function: plugins: [ArchiverPlugin({...})]

error Error: Cannot find module 'vite' ↓

cause Vite is not installed or version mismatched (plugin requires Vite 6/7/8).

fix

Install a compatible Vite version: npm install vite@^6.0.0

error Error: Invalid archive type: 'tgz'. Supported types are 'zip' and 'tar'. ↓

cause Passing an unsupported archive type like 'tgz' (should be 'tar' for gzipped tar).

fix

Use archiveType: 'tar' and optionally set archiveTarOptions.gzip: true.

Warnings

breaking Since v0.3.0, Vite 6+ is required; Vite 5 and below are no longer supported. ↓

fix Upgrade Vite to ^6.0.0 || ^7.0.0 || ^8.0.0; or pin plugin to v0.2.x for Vite 5 support.

breaking Since v0.2.0, the plugin is ESM-only. CommonJS require() will throw an error. ↓

fix Use import instead of require, and ensure your project is configured for ESM (e.g., "type": "module" in package.json).

gotcha The default archive directory is Vite's build.outDir. If outDir is not set, it defaults to 'dist'. Make sure outDir exists or is created during build. ↓

fix Explicitly set build.outDir in Vite config, or ensure the output directory is generated by Vite.

gotcha The formatTemplate uses dayjs formatting tokens. If you include invalid tokens (e.g., 'YYYY' is valid, but 'YYY' is not), the archive filename will have unexpected characters. ↓

fix Use dayjs-compatible format tokens: YYYY, MM, DD, HH, mm, ss, etc.

gotcha The 'open' option is intended to open the archive directory after build. This may not work in headless CI environments or on all operating systems. ↓

fix Set open: false in CI environments, or use an environment variable to conditionally enable it.

Install

npm install vite-plugin-archiver

yarn add vite-plugin-archiver

pnpm add vite-plugin-archiver

Imports

default

wrong

const ArchiverPlugin = require('vite-plugin-archiver')

correct

import ArchiverPlugin from 'vite-plugin-archiver'

Module is ESM-only; CommonJS require() will fail. Default export is the plugin function.

default (with type)
```
import type { VitePluginArchiverOptions } from 'vite-plugin-archiver'
```
TypeScript users should import the options type for type safety. The default export is still the plugin.

plugin usage in vite.config.ts

wrong

export default defineConfig({
  plugins: [ArchiverPlugin({ archiveType: 'zip' }).plugin] // No .plugin property
})

correct

import { defineConfig } from 'vite';
import ArchiverPlugin from 'vite-plugin-archiver';

export default defineConfig({
  plugins: [ArchiverPlugin({ archiveType: 'zip' })]
})

The plugin is a function that returns a Vite plugin object; no need to access a subproperty.

Quickstart

Quick setup of vite-plugin-archiver with ZIP output, custom name template, and compression options.

// install: npm i vite-plugin-archiver -D

// vite.config.ts
import { defineConfig } from 'vite'
import ArchiverPlugin from 'vite-plugin-archiver'

export default defineConfig({
  build: {
    outDir: 'dist'
  },
  plugins: [
    ArchiverPlugin({
      archiveType: 'zip',          // 'zip' or 'tar'
      archiveZipOptions: {
        zlib: { level: 9 }        // compression level (0-9)
      },
      formatTemplate: 'YYYY-MM-DD-HH-mm-ss',  // date-based filename
      open: false                  // auto-open archive directory?
    })
  ]
})

// After build, creates dist/2025-03-25-12-00-00.zip (or .tar)