https://github.com/koajs/compress
Compress middleware for koa
https://github.com/koajs/compress
Last synced: 1 day ago
JSON representation
Compress middleware for koa
- Host: GitHub
- URL: https://github.com/koajs/compress
- Owner: koajs
- License: mit
- Created: 2013-08-20T08:29:58.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2026-01-06T09:30:22.000Z (about 1 month ago)
- Last Synced: 2026-02-06T15:36:49.261Z (8 days ago)
- Language: JavaScript
- Size: 500 KB
- Stars: 445
- Watchers: 8
- Forks: 37
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- License: LICENSE
Awesome Lists containing this project
- awesome-koa - compress - Compress middleware for koa (Middleware)
- awesome-koa - koa-compress - 用于压缩的中间件。   (仓库 / 中间件)
README
# Koa Compress
[](https://github.com/koajs/compress/actions?query=workflow%3A%22Node.js+CI%22+branch%3Amaster)
[](https://codecov.io/gh/koajs/compress)
Compress middleware for Koa
## Example
```js
const compress = require("koa-compress");
const Koa = require("koa");
const app = new Koa();
app.use(
compress({
filter(content_type) {
return /text/i.test(content_type);
},
threshold: 2048,
gzip: {
flush: require("zlib").constants.Z_SYNC_FLUSH,
},
deflate: {
flush: require("zlib").constants.Z_SYNC_FLUSH,
},
zstd: {
flush: require("zlib").constants.Z_SYNC_FLUSH,
},
br: false, // disable brotli
}),
);
```
## Maintainers
- Lead: @jonathanong [@jongleberry](https://twitter.com/jongleberry)
- Team: @koajs/compress
## Options
### filter\
```ts
function (mimeType: string): Boolean {
}
```
An optional function that checks the response content type to decide whether to compress.
By default, it uses [compressible](https://github.com/jshttp/compressible).
### options.threshold\
Minimum response size in bytes to compress or a function that returns such response (see below).
Default `1024` bytes or `1kb`.
### options[encoding]\
The current encodings are, in order of preference: `br`, `zstd`, `gzip`, `deflate`.
Setting `options[encoding] = {}` will pass those options to the encoding function.
Setting `options[encoding] = false` will disable that encoding.
It can be a function that returns options (see below).
#### options.br
[Brotli compression](https://en.wikipedia.org/wiki/Brotli) is supported in node v11.7.0+, which includes it natively.
As of v5.1.0, the default quality level is 4 for performance reasons.
#### options.zstd
[Zstandard compression](https://en.wikipedia.org/wiki/Zstandard) is natively supported in the Node.js API. Minimum supported version: `v22.15.0` (LTS); also available on the Current line starting from `v23.8.0+`. This middleware performs runtime feature detection for `zlib.createZstdCompress`; if present, Zstd is enabled, otherwise it is skipped—no version configuration required.
### options.defaultEncoding\
An optional string, which specifies what encoders to use for requests without
[Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding).
Default `identity`.
The standard dictates to treat such requests as `*` meaning that all compressions are permissible,
yet it causes very practical problems when debugging servers with manual tools like `curl`, `wget`, and so on.
If you want to enable the standard behavior, just set `defaultEncoding` to `*`.
## Manually turning compression on and off
You can always enable compression by setting `ctx.compress = true`.
You can always disable compression by setting `ctx.compress = false`.
This bypasses the filter check.
```js
app.use((ctx, next) => {
ctx.compress = true;
ctx.body = fs.createReadStream(file);
});
```
`ctx.compress` can be an object similar to `options` above, whose properties (`threshold` and encoding options)
override the global `options` for this response and bypass the filter check.
## Functional properties
Certain properties (`threshold` and encoding options) can be specified as functions. Such functions will be called
for every response with three arguments:
- `type` — the same as `ctx.response.type` (provided for convenience)
- `size` — the same as `ctx.response.length` (provided for convenience)
- `ctx` — the whole context object, if you want to do something unique
It should return a valid value for that property. It is possible to return a function of the same shape,
which will be used to calculate the actual property.
Example:
```js
app.use((ctx, next) => {
// ...
ctx.compress = (type, size, ctx) => ({
br: size && size >= 65536,
gzip: size && size < 65536,
});
ctx.body = payload;
});
```
Read all about `ctx` in https://koajs.com/#context and `ctx.response` in https://koajs.com/#response