Node.js Compression Middleware with Brotli Support

Common errors

• TypeError: Cannot read properties of undefined (reading 'filter') or compression is not a function

  cause Incorrect import statement or attempting to destructure a default export.
  fix For ESM, use `import compression from 'compression-next';`. For CommonJS, use `const compression = require('compression-next');`. Do not use named imports like `import { compression } from 'compression-next';`.

• Brotli compression not applied / Response not compressed with 'br' encoding

  cause Node.js version is too old, client does not support Brotli (missing 'br' in Accept-Encoding header), or the response content type is deemed incompressible.
  fix Upgrade Node.js to v11.7.0 / v10.16.0 or newer. Verify the client's `Accept-Encoding` header includes 'br'. Ensure the response `Content-Type` is recognized as compressible or provide a custom `filter` function.

• Response body is not compressed despite `compression-next` being active in Express

  cause The default `filter` function blocked compression, `Cache-Control: no-transform` header was present, or a custom `filter` returned `false`.
  fix Inspect HTTP response headers for `Cache-Control: no-transform`. Check `res.getHeader('Content-Type')` to ensure it's a compressible type. Debug any custom `filter` function logic to ensure it returns `true` when compression is desired.

Warnings

• breaking Brotli compression is only supported on Node.js versions v11.7.0 and v10.16.0 or newer. Attempts to use Brotli on older Node.js versions will result in an error or fallback to Gzip/Deflate if client supports it.
  Fix: Ensure your Node.js environment is at least v11.7.0 or v10.16.0 to leverage Brotli compression. Refer to 'engines' field in package.json.
• gotcha This package is a temporary fork. It's intended to be used until Brotli support is merged into the upstream `expressjs/compression` library. Developers should plan for a future migration back to the official package.
  Fix: Monitor the `expressjs/compression` repository for Brotli integration. Once available, plan to migrate your application to the official package for long-term stability and maintenance.
• gotcha Responses containing a `Cache-Control` header with the `no-transform` directive will not be compressed by this middleware. This is by design, adhering to HTTP caching standards.
  Fix: If compression is desired, ensure that the `Cache-Control` header does not include `no-transform`. Adjust server or proxy configurations if this header is being set unintentionally.
• gotcha The default `filter` function relies on the response's `Content-Type` header and the `compressible` module to decide whether to compress. If the `Content-Type` is missing or indicates an incompressible type, the response will not be compressed.
  Fix: Always set an appropriate `Content-Type` header for your responses. For custom compression logic, provide your own `filter` function in the middleware options.

Install

• npm install compression-next npm
• yarn add compression-next yarn
• pnpm add compression-next pnpm

Imports

• default export (middleware function)
  wrong:

  import { compression } from 'compression-next';

  correct:

  import compression from 'compression-next';

  The package exports the middleware function as its default export for ESM.
• CommonJS export

  const compression = require('compression-next');

  Standard CommonJS import for Node.js environments.
• filter utility

  import compression from 'compression-next'; const customFilter = (req, res) => compression.filter(req, res);

  The default filter function is exposed as a property on the middleware function, allowing custom filter logic to leverage the default behavior.

Quickstart

This quickstart demonstrates how to integrate `compression-next` with an Express application, applying compression to HTTP responses. It shows basic usage with options like compression level and a custom filter.

import express from 'express';
import compression from 'compression-next';
import { Z_BEST_COMPRESSION, constants } from 'zlib'; // Import zlib constants for options

const app = express();
const port = 3000;

// Apply compression middleware
app.use(compression({
  // For gzip/deflate, use 'level' option
  level: Z_BEST_COMPRESSION, // Example: apply best gzip/deflate compression
  // For brotli specific parameters, use 'params'
  // params: {
  //   [constants.BROTLI_PARAM_MODE]: constants.BROTLI_MODE_TEXT,
  //   [constants.BROTLI_PARAM_QUALITY]: constants.BROTLI_MAX_QUALITY
  // },
  filter: (req, res) => {
    if (req.headers['x-no-compression']) {
      // Example: Do not compress responses with a specific header
      return false;
    }
    // Fallback to the default filter function (which uses 'compressible' module)
    return compression.filter(req, res);
  }
}));

// Route for a simple text response
app.get('/', (req, res) => {
  res.send('Hello World! This response should be compressed.');
});

// Route for a larger JSON response to better demonstrate compression effect
app.get('/data', (req, res) => {
  const largeData = Array(500).fill({ id: Math.random(), value: 'some repetitive text here for good compression effect and larger payload size to showcase middleware functionality.' });
  res.json(largeData);
});

app.listen(port, () => {
  console.log(`Server listening at http://localhost:${port}`);
  console.log('Test with curl -H "Accept-Encoding: gzip, deflate, br" http://localhost:3000/data');
  console.log('And without: curl http://localhost:3000/data');
});