Node.js HTTP Compression Middleware

Common errors

• Error: Brotli: Unsupported encoding

  cause Attempting to use Brotli compression (`br`) in a Node.js environment that does not support it (versions older than v10.16.0 or v11.7.0).
  fix Upgrade your Node.js version to at least v10.16.0 or v11.7.0, or remove the `brotli` options from the `compression` middleware configuration.

• TypeError: app.use is not a function

  cause The `compression` middleware is being applied to an object that is not an Express application instance or router, or `express()` was not correctly called.
  fix Ensure that `app` is a valid Express application instance (e.g., `const app = express();`) or an Express router, and that `app.use()` is called correctly with the middleware.

• Warning: Can't set headers after they are sent.

  cause This warning can occur if another middleware or route handler attempts to modify response headers after `compression` (or another middleware) has already sent headers to the client, typically because the response body has started streaming.
  fix Review the order of your middleware and ensure that all header-modifying operations occur before the `compression` middleware and before any part of the response body is flushed.

Warnings

• gotcha Brotli compression (encoding 'br') is only supported in Node.js versions v11.7.0 and later, or v10.16.0 and later. Attempting to use Brotli options on older Node.js versions will result in an unsupported encoding error or silent failure to compress.
  Fix: Ensure your Node.js environment meets the minimum version requirements for Brotli support, or configure the middleware to only use gzip/deflate on older environments.
• gotcha The middleware will explicitly skip compression if the `Cache-Control` response header contains the `no-transform` directive. This is standard HTTP behavior to prevent intermediaries from altering content, but can sometimes lead to unexpected uncompressed responses if not intended.
  Fix: If you desire compression for responses with `Cache-Control: no-transform`, you must manually remove or modify that header before the `compression` middleware is applied. However, consider the implications for caching and proxies.
• gotcha The default `filter` function relies on the `compressible` package to determine if a `Content-Type` is suitable for compression. If you're serving custom or unusual `Content-Type` headers that you wish to compress, you may need to provide a custom `filter` function.
  Fix: Implement a custom `filter` function in the `compression` options that explicitly checks for your desired `Content-Type` headers alongside or instead of the default logic.
• breaking While not a direct breaking change from `compression` itself, Node.js `zlib` API constants used for options (like `Z_DEFAULT_COMPRESSION`) are available directly on `zlib` module from Node.js v11.0.0+. For older Node.js versions, they might be nested or less consistently exposed, potentially affecting options configuration.
  Fix: For wider compatibility across Node.js versions, avoid direct references to `zlib.constants` for older Node.js versions if possible, or provide fallback values. However, `compression` typically handles this gracefully internally.

Install

• npm install compression npm
• yarn add compression yarn
• pnpm add compression pnpm

Imports

• compression
  wrong:

  import { compression } from 'compression';

  correct:

  import compression from 'compression';

  The `compression` module exports a default function. Even if using ES modules, it's typically imported as a default.
• compression

  const compression = require('compression');

  This is the standard CommonJS import pattern shown in the documentation and prevalent in older Node.js/Express applications.
• CompressionOptions
  wrong:

  import { CompressionOptions } from 'compression';

  correct:

  import type { CompressionOptions } from 'compression';

  When using TypeScript, type definitions are often provided for the configuration options. This is a type-only import.

Quickstart

This quickstart demonstrates setting up `compression` middleware in an Express application, including custom filtering and Brotli-specific options, to serve compressed HTML content.

import express from 'express';
import compression from 'compression';

const app = express();

// Use the compression middleware
app.use(compression({
  level: 6, // Default compression level
  filter: (req, res) => {
    if (req.headers['x-no-compression']) {
      // don't compress responses with this header
      return false;
    }
    // fallback to standard filter function
    return compression.filter(req, res);
  },
  brotli: { // Brotli specific options, requires Node.js >= 10.16.0 or >= 11.7.0
    params: {
      [compression.constants.BROTLI_PARAM_QUALITY]: 4
    }
  }
}));

app.get('/', (req, res) => {
  res.type('text/html');
  res.send(`
    <!DOCTYPE html>
    <html>
    <head><title>Compressed Page</title></head>
    <body>
      <h1>Hello, Compressed World!</h1>
      <p>This is a lengthy paragraph to ensure the response body is large enough to benefit from compression. The compression middleware will automatically compress this content if the client supports it.</p>
      <p>Current time: ${new Date().toISOString()}</p>
      <p>You can inspect the 'Content-Encoding' header in your browser's developer tools or by using 'curl -H "Accept-Encoding: gzip" http://localhost:3000 -v' to confirm compression.</p>
    </body>
    </html>
  `);
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Try visiting in your browser or using curl -H "Accept-Encoding: gzip" http://localhost:3000 -v');
});