A predicate that checks the response MIME type to decide whether to compress.
Default: compressible.
options.threshold<String|Number|Function>
Minimum response size in bytes to compress.
Can also be a string parsed by bytes() (e.g. "1kb") or a function (see Functional properties).
Default: 1024.
options[encoding]<Object|Function>
Supported encodings in default preference order: zstd, br, gzip, deflate.
Setting options[encoding] = {} passes those options to the corresponding zlib compressor.
Setting options[encoding] = false disables that encoding.
Brotli compression is available natively in all supported Node.js versions.
The default quality level is 4 for performance reasons.
options.zstd
Zstandard compression is natively supported starting from Node.js v22.15.0 (LTS) and v23.8.0 (Current). The middleware detects zlib.createZstdCompress at runtime; if available, zstd is enabled automatically, otherwise it is skipped.
options.defaultEncoding<String>
Encoding assumed when the client sends no
Accept-Encoding header.
Default: "identity" (no compression).
The HTTP spec treats a missing header as * (any encoding is acceptable),
but that causes problems when debugging with tools like curl or wget.
Set defaultEncoding to "*" to restore spec-compliant behavior.
options.rejectUnacceptable<Boolean>
What to do when the client refuses every encoding the middleware can send, identity included (for example, Accept-Encoding: identity;q=0).
By default, the response goes out uncompressed.
Set rejectUnacceptable to true to respond with 406 Not Acceptable instead.
It applies only to responses that pass the filter and the threshold.
Default: false.
Manually turning compression on and off
You can force compression by setting ctx.compress = true (bypasses the filter check).
You can disable compression by setting ctx.compress = false.
ctx.compress can also be an options object (same shape as the middleware options).
Its threshold, rejectUnacceptable, and encoding properties override the global defaults for this response.
Note: an options object does not bypass the filter check — only true does.
Live streams
The threshold applies to a stream only when you set Content-Length.
Otherwise, Node.js streams, ReadableStream bodies, and Response bodies are compressed whenever the filter accepts their type.
A compressor holds data until it has enough to compress, so a live stream, such as server-sent events, can reach the client late.
To send a live stream as it's written, set ctx.compress = false:
app.use((ctx, next) => { ctx.compress = false; ctx.type = "text/event-stream"; ctx.body = events; // a stream that writes each event as it happens});
Functional properties
The threshold and per-encoding options can be functions. They are called
for every response with three arguments:
type — same as ctx.response.type
size — the response size in bytes, or undefined for a stream without Content-Length
ctx — the full Koa context object
The function should return a valid value for that property.
Returning another function of the same shape is allowed — it will be called in turn.