compression

compression is the standard Node.js middleware for compressing HTTP response bodies on the fly. Dropped into an Express (or Connect-style) app with a single app.use(compression()) call, it negotiates gzip, deflate, or Brotli encoding against the client’s Accept-Encoding header and pipes the response body through the matching Node.js zlib stream, cutting payload size for JSON APIs, HTML pages, and static assets without any changes to route handlers.

Under the hood it works by monkey-patching res.write, res.end, and res.on so it can buffer writes until response headers are about to be sent, at which point it decides whether to compress based on content type, a configurable byte threshold, and the Cache-Control: no-transform directive. It also adds a res.flush() method so streaming use cases like Server-Sent Events can force partially-compressed data out to the client immediately, and it exposes its default content-type filter (compression.filter) so applications can extend rather than replace it.

What You Get

• A single middleware function — compression() — that works with Express, Connect, or plain http.createServer request handlers
• Automatic content negotiation across gzip, deflate, and Brotli (where the Node.js runtime supports it) via the negotiator package
• A configurable byte threshold (default 1kb) so tiny responses skip compression overhead entirely
• A res.flush() method for forcing buffered compressed data to the client, needed for Server-Sent Events and other streaming responses
• Respect for Cache-Control: no-transform so responses that must not be altered are never compressed
• A customizable filter function (extending the built-in compression.filter) to control which responses get compressed by content type

Common Use Cases

• Adding global response compression to an Express API with one app.use(compression()) call
• Compressing HTML/CSS/JS responses served by a static file middleware chain
• Keeping Server-Sent Event streams responsive under compression by calling res.flush() after each write
• Wiring compression directly into a raw http.createServer handler for apps not using a framework

Under The Hood

Architecture Single-file middleware (index.js, ~260 lines) implementing a classic Express/Connect factory pattern: compression(options) returns a request handler that monkey-patches res.write, res.end, and res.on to intercept response writes, buffering any listeners until an onHeaders callback (from the on-headers package) fires just before headers are sent — the point at which it inspects Content-Type, Content-Length, and Cache-Control to decide whether to wrap the response in a zlib stream. Content negotiation is delegated to Negotiator against a fixed supported/preferred encoding order, and small pure helper functions (chunkLength, toBuffer, shouldCompress, shouldTransform, headersSent) keep the decision logic testable in isolation. There’s no internal layering beyond this single closure — the core abstraction is the response monkey-patch itself, a narrow but well-contained risk surface for a module this size.

Tech Stack Pure Node.js/JavaScript, CommonJS, no build step or TypeScript, targeting engines: node >= 0.8.0. Runtime dependencies are all small, single-purpose Express-ecosystem packages — bytes for threshold parsing, compressible for content-type filtering, negotiator for Accept-Encoding negotiation, on-headers for header-flush timing, safe-buffer and vary for compatibility — with the actual compression implemented directly against Node’s built-in zlib module (gzip, deflate, and conditionally Brotli). Dev tooling is ESLint (eslint-config-standard) for linting and Mocha, Supertest, and nyc for testing and coverage, with GitHub Actions running CI.

Code Quality An extensive Mocha test suite (over a thousand lines) exercises HEAD requests, unknown and negotiated encodings, threshold edge cases, Cache-Control no-transform behavior, HTTP/2 (feature-detected and skipped where unsupported), and flush/streaming behavior, all driven through Supertest against a real http.createServer. There are no type definitions or TypeScript, but ESLint enforces consistent style and the implementation favors small, explicit, guard-clause-heavy functions over deep nesting — appropriate for middleware that must never throw into the request pipeline.

API Design The public surface is minimal and idiomatic: compression([options]) returns a standard (req, res, next) handler, so integration is a single app.use(compression()) line with zero required configuration. Options (threshold, filter, level, brotli, strategy, memLevel, windowBits, enforceEncoding) are well documented in the README with sensible defaults, and the exposed compression.filter lets consumers extend rather than replace the default behavior. Documentation lives only in the README and changelog with no separate docs site or bundled TypeScript types, so editor autocompletion for options relies on external @types packages.