Koa Compress Middleware

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES Module context (e.g., in a `.mjs` file or when `"type": "module"` is set in `package.json`).
  fix Change 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

  cause Incorrectly providing the `flush` option for `gzip` or `deflate` settings, often due to not importing `zlib.constants` or using an undefined value.
  fix Ensure 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

  cause 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.
  fix To 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.

  cause The response's MIME type does not match the `filter` predicate, or the response size is below the `threshold` configured in the middleware options.
  fix Review 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.

Warnings

• breaking The 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.
  Fix: To restore the spec-compliant behavior, explicitly set `defaultEncoding: '*'` in the middleware options: `compress({ defaultEncoding: '*' })`.
• breaking Version 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.
  Fix: Ensure 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.
• 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.
  Fix: Upgrade 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.
• gotcha When 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.
  Fix: Always 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`.

Install

• npm install koa-compress npm
• yarn add koa-compress yarn
• pnpm add koa-compress pnpm

Imports

• compress
  wrong:

  const compress = require('koa-compress');

  correct:

  import compress from '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
  wrong:

  import { compress } from 'koa-compress';

  correct:

  const compress = require('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
  wrong:

  import * as zlib from 'zlib'; const flush = zlib.Z_SYNC_FLUSH;

  correct:

  import { constants as zlibConstants } from 'zlib';

  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.

Quickstart

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');
});