Koa Compress

Compress middleware for Koa

Example

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
• Team: @koajs/compress

Options

filter<Function>

function (mimeType: string): Boolean {

}

An optional function that checks the response content type to decide whether to compress. By default, it uses compressible.

options.threshold<String|Number|Function>

Minimum response size in bytes to compress or a function that returns such response (see below). Default 1024 bytes or 1kb.

options[encoding]<Object|Function>

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 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 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<String>

An optional string, which specifies what encoders to use for requests without 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.

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:

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