Vite Plugin Compression

#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

#Tarball Plugin Options

#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 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>

#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