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.
compress
✓ import compress from 'koa-compress';
✗ const compress = require('koa-compress');
While CommonJS `require` is shown in old examples, ESM `import` is the preferred modern approach for Koa applications, especially with TypeScript. This package exports a default function.
compress
✓ const compress = require('koa-compress');
✗ import { compress } from 'koa-compress';
For CommonJS environments, `require('koa-compress')` directly returns the middleware function, which is a default export. Do not attempt named imports with CommonJS.
CompressOptions
✓ import type { CompressOptions } from 'koa-compress';
When using TypeScript, import `CompressOptions` to type the configuration object passed to the middleware.
constants
✓ import { constants as zlibConstants } from 'zlib';
✗ import * as zlib from 'zlib'; const flush = zlib.Z_SYNC_FLUSH;
For configuring `gzip` or `deflate` options like `flush`, you need to import `constants` directly from Node.js's built-in `zlib` module. Alias it for clarity.
This quickstart demonstrates how to integrate `koa-compress` into a Koa application using ESM imports. It shows basic configuration, including `filter`, `threshold`, and algorithm-specific options using `zlib.constants`, and illustrates how to control compression manually via `ctx.compress`.
import Koa from 'koa';
import compress from 'koa-compress';
import { constants as zlibConstants } from 'zlib'; // Required for zlib options
const app = new Koa();
// Example of how to manually control compression for specific routes or conditions
app.use(async (ctx, next) => {
// Forcing compression (bypasses filter)
// ctx.compress = true;
// Disabling compression
// ctx.compress = false;
// Overriding options for a specific response
// ctx.compress = { threshold: 10, gzip: { level: 9 } };
await next();
});
app.use(
compress({
// Predicate function to determine if a response should be compressed
filter(content_type) {
return /text|json|javascript/i.test(content_type || '');
},
// Minimum response size in bytes to trigger compression
threshold: 2048,
gzip: {
flush: zlibConstants.Z_SYNC_FLUSH, // Use constants from Node's zlib
level: 6 // Default gzip compression level
},
deflate: {
flush: zlibConstants.Z_SYNC_FLUSH
},
// Brotli (br) is enabled by default. Set to false to disable or provide options.
// br: false,
// br: { quality: 4 }, // Example: Lower brotli quality for faster compression
// Zstandard (zstd) is automatically enabled if supported by Node.js runtime.
// zstd: { level: 1 }, // Example: Zstd compression level
defaultEncoding: 'identity' // When client sends no Accept-Encoding header
}),
);
// A route that serves a compressible body
app.use((ctx) => {
ctx.type = 'text/plain';
// Ensure body size exceeds the threshold for compression to apply
ctx.body = 'This is a long string that will be compressed by koa-compress middleware if the client supports it and the size exceeds the threshold.'
.repeat(50);
});
const port = 3000;
app.listen(port, () => {
console.log(`Koa server running on http://localhost:${port}`);
console.log('Test compression: curl -H "Accept-Encoding: gzip" -I http://localhost:3000');
});
Debug
Known issues
breakingThe default behavior for clients sending no `Accept-Encoding` header changed in `v5.0.0`. It now defaults to `'identity'` (no compression) instead of the HTTP spec-compliant `'*'` (any encoding). This can affect debugging tools like `curl` that often omit `Accept-Encoding` by default.fixTo restore the spec-compliant behavior, explicitly set `defaultEncoding: '*'` in the middleware options: `compress({ defaultEncoding: '*' })`. affects: >=5.0.0
breakingVersion 4.0.0 dropped support for Node.js versions below 10. Additionally, the way options were passed to compression functions (like `gzip`, `deflate`, `br`) changed significantly. Previous configurations may no longer be valid.fixEnsure your Node.js environment is `v10` or newer. Review the new options structure in the `koa-compress` documentation and update your configuration objects for `gzip`, `deflate`, and `br` accordingly. Brotli (br) support was also introduced in this version.
affects: >=4.0.0
gotcha`zstandard` (zstd) compression is only supported natively in specific Node.js versions: `v22.15.0` (LTS) or `v23.8.0` (Current) and above. If your Node.js version is older, `zstd` compression will be silently skipped, even if configured.fixUpgrade your Node.js environment to a version that natively supports Zstandard (e.g., Node.js 22.15.0+ or 23.8.0+). The middleware automatically detects `zlib.createZstdCompress` at runtime; no code changes are needed if the runtime supports it.
affects: <22.15.0 || <23.8.0 (for zstd only)
gotchaWhen configuring `gzip` or `deflate` options, especially the `flush` property, direct numeric values or incorrect string literals can lead to errors. Node.js's `zlib` module expects specific `constants` for these settings.fixAlways import and use the `constants` object from Node.js's built-in `zlib` module. For example, `import { constants as zlibConstants } from 'zlib';` and then use `flush: zlibConstants.Z_SYNC_FLUSH`. affects: >=3.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use `require()` in an ES Module context (e.g., in a `.mjs` file or when `"type": "module"` is set in `package.json`).
fixChange your import statement to `import compress from 'koa-compress';` to use ES Module syntax. Ensure `import Koa from 'koa';` and other imports are also using ESM.
ERR_INVALID_ARG_TYPE: The 'flush' argument must be one of type number. Received type undefined
Incorrectly providing the `flush` option for `gzip` or `deflate` settings, often due to not importing `zlib.constants` or using an undefined value.
fixEnsure you import `constants` from Node.js's `zlib` module: `import { constants as zlibConstants } from 'zlib';`. Then, use these constants for flush options: `gzip: { flush: zlibConstants.Z_SYNC_FLUSH }`. Expected 'options.br' to be object or function but got false
Passing a boolean value (`false`) to an encoding option (e.g., `br`) when the `options[encoding]` property expects an object for configuration or a function for dynamic options, and the middleware expects an explicit object for that type of configuration.
fixTo disable an encoding like `br`, simply omit it from the `compress` options object or explicitly set `br: false`. If you intend to provide options, use an object: `br: { quality: 4 }`. The error message in this specific form indicates a misunderstanding or a type mismatch with expected configuration. Response is not compressed (e.g., 'Content-Encoding' header missing) even when expected.
The response's MIME type does not match the `filter` predicate, or the response size is below the `threshold` configured in the middleware options.
fixReview the `filter` function to ensure it correctly identifies the `ctx.type` for compression. Check the `threshold` value against `ctx.response.length` (or `ctx.body` size) to confirm the response is large enough. You can also temporarily force compression with `ctx.compress = true;` for debugging specific routes.
Audit
Dependencies
No dependency data recorded yet.