compression-webpack-plugin

compression-webpack-plugin hooks into webpack’s asset-processing pipeline to generate compressed sibling files (.gz, .br, .zst, or a custom extension) for every matching build output, so a web server can serve pre-compressed assets via Content-Encoding instead of compressing them on every request. It supports Node’s built-in zlib algorithms (gzip, deflate, brotliCompress, zstdCompress) out of the box, and accepts a custom compression function for libraries like Zopfli.

Compression decisions are configurable per project: test/include/exclude filter which assets get processed, threshold skips small files, and minRatio skips files that don’t compress well enough to be worth serving twice. Results are cached through webpack’s own compilation cache keyed by content hash, so unchanged assets are not recompressed on incremental rebuilds, and deleteOriginalAssets controls whether the uncompressed originals are kept alongside the compressed ones.

What You Get

• Built-in support for gzip, deflate, and Brotli via Node’s native zlib module, with Zstandard support on Node 22.15+
• Pluggable custom algorithm function for other compressors (e.g. Zopfli via @gfx/zopfli)
• Fine-grained asset filtering with test/include/exclude regex or string rules
• threshold and minRatio options to skip files too small or too incompressible to bother with
• Persistent, content-hash-keyed caching through webpack’s compilation cache so rebuilds don’t recompress unchanged assets
• deleteOriginalAssets (including a keep-source-map mode) to control whether uncompressed originals remain in the output

Common Use Cases

• Pre-gzip or pre-Brotli static assets for a CDN or Nginx gzip_static/brotli_static setup so requests skip on-the-fly compression
• Shipping smaller JS/CSS bundles to reduce Time to First Byte for static sites and SPAs deployed to object storage
• Serving Brotli-compressed assets to browsers that support it while leaving originals for uncompressed fallbacks
• Producing zstd-compressed assets for internal services or edge platforms that prefer Zstandard’s speed/ratio tradeoff

Under The Hood

Architecture The plugin is a single class (src/index.js) implementing webpack’s WebpackPluginInstance contract: apply(compiler) taps compiler.hooks.thisCompilation, then registers an async processAssets hook at PROCESS_ASSETS_STAGE_OPTIMIZE_TRANSFER that filters candidate assets with ModuleFilenameHelpers.matchObject, runs the configured compression algorithm, and either replaces the original asset or emits a related compressed sibling depending on deleteOriginalAssets. Compressed output is stored in a per-plugin cache obtained via compilation.getCache, keyed by a serialized options+asset descriptor and the asset’s lazy hashed etag, so unchanged inputs skip recompression entirely on incremental builds. It is a tightly scoped, single-responsibility design with one clear extension seam (a custom algorithm function) rather than a layered or pluggable architecture.

Tech Stack Plain Node.js (>=20.9) with no application framework: runtime dependencies are schema-utils for validating constructor options against a JSON schema (src/options.json) and serialize-javascript for building deterministic cache keys, with webpack as a peer dependency. The build pipeline compiles src to dist with Babel and separately emits hand-checked TypeScript declarations via tsc --declaration --emitDeclarationOnly from JSDoc annotations, with ESLint’s flat config (eslint-config-webpack), Prettier, and cspell all wired into a combined lint script.

Code Quality Testing is extensive and organized by concern: dedicated Jest suites exist per option (algorithm, compressionOptions, deleteOriginalAssets, exclude, filename, include, minRatio, test, threshold, validate-options) plus a main CompressionPlugin.test.js and snapshot fixtures, with coverage collection configured via test:coverage. Errors from the compression algorithm are pushed onto compilation.errors rather than thrown, keeping the build from crashing on a single bad asset, and all public options are typed through JSDoc generics that also drive the generated .d.ts file. CI runs lint, type-check, spelling, and tests via a GitHub Actions workflow, plus a separate dependency-review workflow, and commit messages are enforced with commitlint/husky.

What Makes It Unique The plugin doesn’t attempt anything algorithmically novel — it’s a thin, well-integrated wrapper around Node’s native zlib (and any user-supplied compressor). Its real value is in the details: webpack-native persistent caching so recompression is skipped on unchanged assets, a minRatio guard that avoids emitting compressed files bigger than a useful threshold relative to the original, and a relatedName bookkeeping scheme so downstream tooling (webpack stats, manifest plugins) can discover the compressed sibling of any given asset.