Install

$ yarn add vite-plugin-compression2 -D

# or

$ npm install vite-plugin-compression2 -D

# or

$ pnpm add vite-plugin-compression2 -D

Usage

Basic Usage

import { defineConfig } from 'vite'
import { compression } from 'vite-plugin-compression2'

export default defineConfig({
  plugins: [
    // ...your plugins
    compression()
  ]
})

Multiple Algorithms

import { compression, defineAlgorithm } from 'vite-plugin-compression2'

export default defineConfig({
  plugins: [
    compression({
      algorithms: [
        'gzip',
        'brotliCompress',
        defineAlgorithm('deflate', { level: 9 })
      ]
    })
  ]
})

Custom Algorithm Function

import { compression, defineAlgorithm } from 'vite-plugin-compression2'

export default defineConfig({
  plugins: [
    compression({
      algorithms: [
        defineAlgorithm(
          async (buffer, options) => {
            // Your custom compression logic
            return compressedBuffer
          },
          { customOption: true }
        )
      ]
    })
  ]
})

With Tarball

import { compression, tarball } from 'vite-plugin-compression2'

export default defineConfig({
  plugins: [
    compression(),
    // If you want to create a tarball archive, use tarball plugin after compression
    tarball({ dest: './dist/archive' })
  ]
})

Options

Compression Plugin Options

params	type	default	description
include	string | RegExp | Array<string | RegExp>	/\.(html|xml|css|json|js|mjs|svg|yaml|yml|toml)$/	Include all assets matching any of these conditions.
exclude	string | RegExp | Array<string | RegExp>	-	Exclude all assets matching any of these conditions.
threshold	number	0	Only assets bigger than this size are processed (in bytes)
algorithms	Algorithms	['gzip', 'brotliCompress']	Array of compression algorithms or defineAlgorithm results
filename	string | function	[path][base].gz or [path][base]. br If algorithm is zstandard be [path][base].zst	The target asset filename pattern
deleteOriginalAssets	boolean	false	Whether to delete the original assets or not
skipIfLargerOrEqual	boolean	true	Whether to skip the compression if the result is larger than or equal to the original file
logLevel	string	info	Control sdout info
artifacts	function	undefined	Sometimes you need to copy something to the final output. This option may help you.

Tarball Plugin Options

params	type	default	description
dest	string	-	Destination directory for tarball

API

defineAlgorithm(algorithm, options?)

Define a compression algorithm with options.

Parameters:

• algorithm: Algorithm name ('gzip' | 'brotliCompress' | 'deflate' | 'deflateRaw' | 'zstandard' | 'gz' | 'br' | 'brotli' | 'zstd') or custom function
• options: Compression options for the algorithm

Returns: [algorithm, options] tuple

Examples:

// Built-in algorithm with default options
defineAlgorithm('gzip')

// Built-in algorithm with custom options
defineAlgorithm('gzip', { level: 9 })

// Brotli with custom quality
defineAlgorithm('brotliCompress', {
  params: {
    [require('zlib').constants.BROTLI_PARAM_QUALITY]: 11
  }
})

// Custom algorithm function
defineAlgorithm(
  async (buffer, options) => {
    // Your compression implementation
    return compressedBuffer
  },
  { customOption: 'value' }
)

Supported Algorithms

Algorithm	Aliases	Extension	Node.js Support	Description
gzip	gz	.gz	All versions	Standard gzip compression with good balance of speed and ratio
brotliCompress	brotli, br	.br	All versions	Brotli compression with better compression ratio than gzip
deflate	-	.gz	All versions	Deflate compression algorithm
deflateRaw	-	.gz	All versions	Raw deflate compression without headers
zstandard	zstd	.zst	>= 22.15.0 or >= 23.8.0	Zstandard compression with excellent speed/ratio balance
Custom Function	-	Custom	All versions	Your own compression algorithm implementation

Algorithm Types

The algorithms option accepts:

type Algorithms =
  | Algorithm[] // ['gzip', 'brotliCompress']
  | DefineAlgorithmResult[] // [defineAlgorithm('gzip'), ...]
  | (Algorithm | DefineAlgorithmResult)[] // Mixed array

Migration

If you're upgrading from v1.x, please check the Migration Guide.

Q & A

FAQ

Examples

Basic Gzip Only

compression({
  algorithms: ['gzip']
})

Multiple Algorithms with Custom Options

compression({
  algorithms: [
    defineAlgorithm('gzip', { level: 9 }),
    defineAlgorithm('brotliCompress', {
      params: {
        [require('zlib').constants.BROTLI_PARAM_QUALITY]: 11
      }
    })
  ]
})

Custom Filename Pattern

compression({
  algorithms: ['gzip'],
  filename: '[path][base].[hash].gz'
})

Delete Original Files

compression({
  algorithms: ['gzip'],
  deleteOriginalAssets: true
})

Size Threshold

compression({
  algorithms: ['gzip'],
  threshold: 1000 // Only compress files larger than 1KB
})

Production Deployment

After building your project with compressed assets, you need to configure your web server to serve these pre-compressed files.

Nginx Configuration

http {
    # Enable gzip_static module to serve pre-compressed .gz files
    gzip_static on;
    
    # Enable brotli_static to serve pre-compressed .br files
    # Requires ngx_brotli module: https://github.com/google/ngx_brotli
    brotli_static on;
    
    # Fallback to dynamic compression if static file not found
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    
    server {
        listen 80;
        server_name example.com;
        root /var/www/html;
        
        location / {
            try_files $uri $uri/ /index.html;
        }
    }
}

Apache Configuration

# Enable mod_deflate for fallback dynamic compression
<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript application/json
</IfModule>

# Serve pre-compressed files
<IfModule mod_rewrite.c>
    RewriteEngine On
    
    # Serve .br file if it exists and client supports brotli
    RewriteCond %{HTTP:Accept-Encoding} br
    RewriteCond %{REQUEST_FILENAME}.br -f
    RewriteRule ^(.*)$ $1.br [L]
    
    # Serve .gz file if it exists and client supports gzip
    RewriteCond %{HTTP:Accept-Encoding} gzip
    RewriteCond %{REQUEST_FILENAME}.gz -f
    RewriteRule ^(.*)$ $1.gz [L]
</IfModule>

# Set correct content-type and encoding headers
<FilesMatch "\.js\.gz$">
    Header set Content-Type "application/javascript"
    Header set Content-Encoding "gzip"
</FilesMatch>

<FilesMatch "\.css\.gz$">
    Header set Content-Type "text/css"
    Header set Content-Encoding "gzip"
</FilesMatch>

<FilesMatch "\.js\.br$">
    Header set Content-Type "application/javascript"
    Header set Content-Encoding "br"
</FilesMatch>

<FilesMatch "\.css\.br$">
    Header set Content-Type "text/css"
    Header set Content-Encoding "br"
</FilesMatch>

Framework Integration

Next.js

For Next.js projects, add the plugin to your Vite configuration if using the App Router with custom server:

// vite.config.js (for custom Next.js setups)
import { defineConfig } from 'vite'
import { compression } from 'vite-plugin-compression2'

export default defineConfig({
  plugins: [
    compression({
      algorithms: ['gzip', 'brotliCompress'],
      threshold: 1024
    })
  ]
})

For standard Next.js builds, configure in next.config.js:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Next.js handles compression differently
  // Use this plugin with custom server or static export
  output: 'export', // For static export
  compress: false // Disable Next.js built-in compression to use pre-compressed files
}

module.exports = nextConfig

Nuxt 3

// nuxt.config.ts
import { compression } from 'vite-plugin-compression2'

export default defineNuxtConfig({
  vite: {
    plugins: [
      compression({
        algorithms: ['gzip', 'brotliCompress'],
        threshold: 1024,
        exclude: [/\.map$/, /stats\.html$/]
      })
    ]
  }
})

SvelteKit

// vite.config.js
import { sveltekit } from '@sveltejs/kit/vite'
import { compression } from 'vite-plugin-compression2'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    sveltekit(),
    compression({
      algorithms: ['gzip', 'brotliCompress'],
      threshold: 1024
    })
  ]
})

Astro

// astro.config.mjs
import { defineConfig } from 'astro/config'
import { compression } from 'vite-plugin-compression2'

export default defineConfig({
  vite: {
    plugins: [
      compression({
        algorithms: ['gzip', 'brotliCompress']
      })
    ]
  }
})

Performance Tips

Compression Level Selection

Choose compression levels based on your deployment strategy:

compression({
  algorithms: [
    // Development: faster builds, lower compression
    defineAlgorithm('gzip', { level: 6 }), // Default level
    
    // Production: slower builds, better compression
    defineAlgorithm('gzip', { level: 9 }), // Maximum compression
    
    // Brotli: quality 10-11 recommended for static assets
    defineAlgorithm('brotliCompress', {
      params: {
        [require('zlib').constants.BROTLI_PARAM_QUALITY]: 11
      }
    })
  ]
})

Recommendations:

• Development/CI: Level 6 (gzip) or Quality 4-6 (brotli) - faster builds
• Production: Level 9 (gzip) or Quality 10-11 (brotli) - best compression
• Balance: Level 7-8 (gzip) or Quality 8-9 (brotli) - good compromise

File Size Threshold

Only compress files that benefit from compression:

compression({
  threshold: 1024, // 1KB minimum - recommended
  algorithms: ['gzip', 'brotliCompress']
})

Why use a threshold?

• Files smaller than 1KB may not benefit from compression
• HTTP overhead can make tiny compressed files slower
• Saves build time and disk space

Multi-Algorithm Strategy

Use both gzip and brotli for maximum compatibility and performance:

compression({
  algorithms: [
    defineAlgorithm('gzip', { level: 9 }),      // Wide browser support (all browsers)
    defineAlgorithm('brotliCompress', {         // Better compression (modern browsers)
      params: {
        [require('zlib').constants.BROTLI_PARAM_QUALITY]: 11
      }
    })
  ]
})

Benefits:

• Brotli: 15-20% better compression than gzip
• Gzip: Fallback for older browsers
• Server automatically serves the best format based on Accept-Encoding header

Selective Compression

Compress only specific file types for optimal results:

compression({
  include: [/\.(js|mjs|json|css|html|svg)$/], // Text-based files
  exclude: [/\.(png|jpg|jpeg|gif|webp|woff|woff2)$/], // Already compressed formats
  threshold: 1024
})

File types that compress well:

• JavaScript/TypeScript (.js, .mjs, .ts)
• CSS (.css)
• HTML (.html)
• JSON (.json)
• SVG (.svg)
• XML (.xml)

File types to skip:

• Images (.png, .jpg, .webp) - already compressed
• Fonts (.woff, .woff2) - already compressed
• Videos (.mp4, .webm) - already compressed

Others

• If you want to analyze your bundle assets, try vite-bundle-analyzer
• tarball option dest means to generate a tarball somewhere
• tarball is based on the ustar format. It should be compatible with all popular tar distributions (gnutar, bsdtar etc)

Node.js Version Requirements

• gzip, brotliCompress, deflate, deflateRaw: All Node.js versions supported
• zstd: Requires Node.js >= 22.15.0 or >= 23.8.0

Note: If you try to use zstd compression on an unsupported Node.js version, the plugin will throw a helpful error message indicating the required version.

Sponsors

LICENSE

MIT

Acknowledgements

NWYLZW

Author

Kanno