# koa-compress

> Compress middleware for koa

Latest version **5.2.2** (published 2026-06-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install koa-compress
pnpm add koa-compress
yarn add koa-compress
bun add koa-compress
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 5.2.2 |
| Published | 2026-06-16 |
| First published | 2013-08-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 12 |
| Dependencies | 5 |
| Unpacked size | 19.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 441 |
| Author | Jonathan Ong |
| Maintainers | elazutkin, coderhaoxin, federomero, niftylettuce, juliangruber, eivifj, dead_horse, tjholowaychuk, jongleberry, fengmk2, titanism |

## Links

- npm: https://www.npmjs.com/package/koa-compress
- Repository: https://github.com/koajs/compress
- Homepage: https://github.com/koajs/compress#readme
- Issues: https://github.com/koajs/compress/issues
- npm.io page: https://npm.io/package/koa-compress

## Dependencies (5)

- [bytes](https://npm.io/package/bytes.md) ^3.1.2
- [negotiator](https://npm.io/package/negotiator.md) ^1.0.0
- [http-errors](https://npm.io/package/http-errors.md) ^2.0.1
- [koa-is-json](https://npm.io/package/koa-is-json.md) ^1.0.0
- [compressible](https://npm.io/package/compressible.md) ^2.0.18

## Recent versions

- 5.2.2 (latest) — 2026-06-16
- 2.0.0 (next) — 2016-02-25
- 5.2.1 — 2026-03-12
- 5.2.0 — 2026-02-11
- 5.1.1 — 2023-04-09
- 5.1.0 — 2021-08-18
- 5.0.1 — 2020-07-06
- 5.0.0 — 2020-07-06
- 4.0.1 — 2020-04-30
- 4.0.0 — 2020-04-28
- 3.1.0 — 2020-04-16
- 3.0.0 — 2018-04-14
- 1.0.9 — 2016-02-17
- 1.0.8 — 2014-09-15
- 1.0.7 — 2014-05-14
- … 8 more at https://npm.io/package/koa-compress/versions

## README

# Koa Compress

[![Node.js CI](https://github.com/koajs/compress/workflows/Node.js%20CI/badge.svg?branch=master)](https://github.com/koajs/compress/actions?query=workflow%3A%22Node.js+CI%22+branch%3Amaster)
[![codecov](https://codecov.io/gh/koajs/compress/branch/master/graph/badge.svg)](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\<Function\>

```ts
function (mimeType: string): boolean {}
```

A predicate that checks the response MIME type to decide whether to compress.
Default: [compressible](https://github.com/jshttp/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](#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.

Can also be a function (see [Functional properties](#functional-properties)).

#### options.br

[Brotli compression](https://en.wikipedia.org/wiki/Brotli) is available natively in all supported Node.js versions.
The default quality level is 4 for performance reasons.

#### options.zstd

[Zstandard compression](https://en.wikipedia.org/wiki/Zstandard) 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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.

## 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`.

```js
app.use((ctx, next) => {
  ctx.compress = true;
  ctx.body = fs.createReadStream(file);
});
```

`ctx.compress` can also be an options object (same shape as the middleware options).
Its `threshold` and encoding properties override the global defaults for this response.
Note: an options object does **not** bypass the filter check — only `true` does.

## Functional properties

The `threshold` and per-encoding options can be functions. They are called
for every response with three arguments:

- `type` &mdash; same as `ctx.response.type`
- `size` &mdash; same as `ctx.response.length`
- `ctx` &mdash; 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.

Example:

```js
app.use(
  compress({
    gzip: (type, size) => (size && size < 65536 ? { level: 9 } : false),
    br: (type, size) => size && size >= 65536,
  }),
);
```

See the Koa documentation for [`ctx`](https://koajs.com/#context) and [`ctx.response`](https://koajs.com/#response).

---
_Source: https://npm.io/package/koa-compress · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._