compression

1.7.11 verified Sat Apr 25 auth: no javascript

Node.js compression middleware for Express/Connect that provides gzip and deflate encoding. Current stable version is 1.8.1 (August 2024). Maintained by the Express.js team with monthly releases. Handles content negotiation, cache-control respecting, and configurable zlib options. Key differentiator is seamless integration with Express routing, supporting threshold, filter, and level settings. Not a standalone compressor; must be used with Node.js HTTP server or framework. Legacy support for Node >=0.8.0.

Common errors

error TypeError: compression is not a function ↓

cause Incorrect import: using `require('compression')` in an ESM environment or importing as default without default import.

fix

Use import compression from 'compression' or use const compression = require('compression').default if using CommonJS in ESM context.

error ERR_INVALID_ARG_TYPE: The "level" argument must be of type number. Received undefined ↓

cause Passing options to `compression()` where `level` is not a number (e.g., string).

fix

Ensure level option is a number between -1 and 9.

error Cannot set property 'writeHead' of undefined ↓

cause Compression middleware was applied after response has already been written or ended (e.g., placed after route handlers).

fix

Move app.use(compression()) before all route handlers.

Warnings

breaking In v1.7.0, changed from using raw Buffer to safe-buffer for improved Buffer API compatibility. This may affect custom compression filter functions that rely on Buffer constructors. ↓

fix Update any code that explicitly uses Buffer to use safe-buffer's Buffer if needed.

deprecated In v1.8.0, the `_header` property is deprecated in favor of `headersSent`. Code that directly checks `res._header` may break in future Node.js versions. ↓

fix Replace `res._header` with `res.headersSent` in custom filter or hook functions.

gotcha Do NOT call `res.end()` or pipe the response before compression middleware runs. The middleware must intercept the response stream; otherwise compression will not be applied and may cause errors. ↓

fix Ensure `compression()` is inserted in middleware stack before any route handlers that write to the response.

gotcha Compression is automatically skipped if the response has `Cache-Control: no-transform`. This is a feature to respect CDN and proxy transformations, but can be surprising if you expect compression overrides. ↓

fix Remove `no-transform` from Cache-Control header if you want forced compression.

breaking In v1.6.0, the default `level` changed from 6 to -1 (zlib default). With newer Node versions, the underlying zlib default may vary, affecting compression ratio consistency. ↓

fix Explicitly set `level` option if you need a specific compression level.

Install

npm install compresion

yarn add compresion

pnpm add compresion

Imports

compression
wrong
```
const compression = require('compression')
```
correct
```
import compression from 'compression'
```
ESM is supported in v1.8+ with conditional exports; default import works. For CommonJS, require('compression') is still valid.
CompressionOptions
```
import type { CompressionOptions } from 'compression'
```
TypeScript users can import the options interface for type safety.

Quickstart

Creates an Express server with compression middleware applied globally to compress responses.

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

const app = express();

// apply compression middleware
app.use(compression());

// normal route
app.get('/data', (req, res) => {
  res.json({ message: 'This response will be compressed' });
});

app.listen(3000, () => console.log('Server listening on port 3000'));