Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
compression
✓ import compression from 'compression';
✗ import { compression } from 'compression';
The `compression` module exports a default function. Even if using ES modules, it's typically imported as a default.
compression
✓ const compression = require('compression');
This is the standard CommonJS import pattern shown in the documentation and prevalent in older Node.js/Express applications.
CompressionOptions
✓ import type { CompressionOptions } from 'compression';
✗ import { CompressionOptions } from 'compression';
When using TypeScript, type definitions are often provided for the configuration options. This is a type-only import.
This quickstart demonstrates setting up `compression` middleware in an Express application, including custom filtering and Brotli-specific options, to serve compressed HTML content.
import express from 'express';
import compression from 'compression';
const app = express();
// Use the compression middleware
app.use(compression({
level: 6, // Default compression level
filter: (req, res) => {
if (req.headers['x-no-compression']) {
// don't compress responses with this header
return false;
}
// fallback to standard filter function
return compression.filter(req, res);
},
brotli: { // Brotli specific options, requires Node.js >= 10.16.0 or >= 11.7.0
params: {
[compression.constants.BROTLI_PARAM_QUALITY]: 4
}
}
}));
app.get('/', (req, res) => {
res.type('text/html');
res.send(`
<!DOCTYPE html>
<html>
<head><title>Compressed Page</title></head>
<body>
<h1>Hello, Compressed World!</h1>
<p>This is a lengthy paragraph to ensure the response body is large enough to benefit from compression. The compression middleware will automatically compress this content if the client supports it.</p>
<p>Current time: ${new Date().toISOString()}</p>
<p>You can inspect the 'Content-Encoding' header in your browser's developer tools or by using 'curl -H "Accept-Encoding: gzip" http://localhost:3000 -v' to confirm compression.</p>
</body>
</html>
`);
});
const PORT = 3000;
app.listen(PORT, () => {
console.log(`Server running on http://localhost:${PORT}`);
console.log('Try visiting in your browser or using curl -H "Accept-Encoding: gzip" http://localhost:3000 -v');
});
Debug
Known issues
gotchaBrotli compression (encoding 'br') is only supported in Node.js versions v11.7.0 and later, or v10.16.0 and later. Attempting to use Brotli options on older Node.js versions will result in an unsupported encoding error or silent failure to compress.fixEnsure your Node.js environment meets the minimum version requirements for Brotli support, or configure the middleware to only use gzip/deflate on older environments.
affects: <10.16.0 || (>=10.0.0 <10.16.0) || (>=11.0.0 <11.7.0)
gotchaThe middleware will explicitly skip compression if the `Cache-Control` response header contains the `no-transform` directive. This is standard HTTP behavior to prevent intermediaries from altering content, but can sometimes lead to unexpected uncompressed responses if not intended.fixIf you desire compression for responses with `Cache-Control: no-transform`, you must manually remove or modify that header before the `compression` middleware is applied. However, consider the implications for caching and proxies.
affects: >=1.0.0
gotchaThe default `filter` function relies on the `compressible` package to determine if a `Content-Type` is suitable for compression. If you're serving custom or unusual `Content-Type` headers that you wish to compress, you may need to provide a custom `filter` function.fixImplement a custom `filter` function in the `compression` options that explicitly checks for your desired `Content-Type` headers alongside or instead of the default logic.
affects: >=1.0.0
breakingWhile not a direct breaking change from `compression` itself, Node.js `zlib` API constants used for options (like `Z_DEFAULT_COMPRESSION`) are available directly on `zlib` module from Node.js v11.0.0+. For older Node.js versions, they might be nested or less consistently exposed, potentially affecting options configuration.fixFor wider compatibility across Node.js versions, avoid direct references to `zlib.constants` for older Node.js versions if possible, or provide fallback values. However, `compression` typically handles this gracefully internally.
affects: <11.0.0
Errors
Common errors & fixes
Error: Brotli: Unsupported encoding
Attempting to use Brotli compression (`br`) in a Node.js environment that does not support it (versions older than v10.16.0 or v11.7.0).
fixUpgrade your Node.js version to at least v10.16.0 or v11.7.0, or remove the `brotli` options from the `compression` middleware configuration.
TypeError: app.use is not a function
The `compression` middleware is being applied to an object that is not an Express application instance or router, or `express()` was not correctly called.
fixEnsure that `app` is a valid Express application instance (e.g., `const app = express();`) or an Express router, and that `app.use()` is called correctly with the middleware.
Warning: Can't set headers after they are sent.
This warning can occur if another middleware or route handler attempts to modify response headers after `compression` (or another middleware) has already sent headers to the client, typically because the response body has started streaming.
fixReview the order of your middleware and ensure that all header-modifying operations occur before the `compression` middleware and before any part of the response body is flushed.
Audit
Dependencies
compressiblerequiredUsed by the default `filter` function to determine if a response's Content-Type is suitable for compression.
bytesrequiredUsed internally for byte-related operations.