compression

Node.js compression middleware

weekly downloads35.4M

versionv1.8.1

licenseMIT

categorybackend

compressiongzipdeflatemiddlewareexpressbrotlihttpstream

Overview

The compression package is a Node.js middleware that automatically compresses HTTP response bodies before sending them to clients. With over 35 million weekly downloads, it's one of the most widely adopted performance optimization tools in the Node.js ecosystem. The middleware intercepts outgoing responses and applies compression algorithms (gzip, deflate, or brotli) when clients indicate support via the Accept-Encoding header.

Compression works by analyzing the Content-Type of responses and applying appropriate compression for text-based content like HTML, CSS, JavaScript, and JSON. The middleware is intelligent enough to skip compression for responses that are too small (where compression overhead exceeds benefits), already compressed content, or responses with Cache-Control: no-transform directives. This automatic handling makes it a plug-and-play solution for most Express and Connect-based applications.

The package is particularly valuable for applications serving large amounts of text-based content. In production environments, compression can reduce response sizes by 60-85% for typical web assets, with some cases achieving up to 90% reduction. This translates directly to faster page load times, reduced bandwidth costs, and improved user experience, especially for users on slower connections or mobile networks.

While compression is highly effective for on-demand compression of dynamic content, teams serving primarily static assets may benefit more from pre-compression strategies or offloading compression to reverse proxies like nginx. The CPU overhead of real-time compression is minimal for most applications, but high-traffic services with tight latency budgets should benchmark the impact.

Quick Start

typescript

const express = require('express');
const compression = require('compression');

const app = express();

app.use(compression({
  level: 6,
  threshold: 1024,
  filter: (req, res) => {
    if (req.headers['x-no-compression']) {
      return false;
    }
    return compression.filter(req, res);
  }
}));

app.get('/api/users', (req, res) => {
  const users = Array.from({ length: 1000 }, (_, i) => ({
    id: i,
    name: `User ${i}`,
    email: `user${i}@example.com`,
    bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'.repeat(5)
  }));
  res.json(users);
});

app.get('/health', (req, res) => {
  res.set('Cache-Control', 'no-transform');
  res.send('OK');
});

app.listen(3000, () => {
  console.log('Server with compression running on port 3000');
});

Use Cases

API response compression: REST APIs returning JSON or XML payloads benefit significantly from compression, especially when returning large datasets, search results, or paginated lists. A 200KB JSON response can be compressed to 30-40KB, reducing mobile data usage and improving response times.

Server-side rendered applications: Applications using template engines like EJS, Pug, or Handlebars that generate HTML on each request see substantial benefits. The generated HTML typically compresses well due to repetitive structure and whitespace.

Express applications with mixed content: Web applications serving both dynamic and static content can use compression as a catch-all solution before implementing more sophisticated caching strategies. It provides immediate performance improvements with minimal code changes.

Microservices communication: Internal service-to-service communication over HTTP can benefit from compression when transferring large payloads, reducing network bandwidth in containerized environments where services communicate frequently.

Legacy application optimization: Adding compression to older Express applications is a quick win that requires minimal code changes and no modifications to existing route handlers, making it ideal for incremental performance improvements.

Pros & Cons

Pros

+Zero-configuration setup with sensible defaults works immediately for most Express applications
+Dramatic bandwidth reduction (60-85%) for text-based content translates to lower hosting costs and faster load times
+Intelligent filtering automatically skips small responses and incompressible content types
+Wide browser support since gzip and deflate are universally supported by all modern and legacy browsers
+Minimal CPU overhead for typical web applications makes it suitable for production use without performance concerns

Cons

−Real-time compression adds CPU overhead that may impact latency in extremely high-traffic scenarios or CPU-constrained environments
−Pre-compressed static files served via nginx or CDN are more efficient than on-demand compression for assets that don't change
−Brotli support requires explicit configuration and Node.js 11.7.0+ while competitors like koa-compress enable it by default
−Default threshold of 1KB may compress responses where the overhead exceeds the benefit, though this is configurable
−No built-in caching of compressed responses means the same content is recompressed on every request unless paired with caching middleware

Install

bash

npm install compression

bash

pnpm add compression

bash

bun add compression

Overview

Quick Start

typescript

const express = require('express');
const compression = require('compression');

const app = express();

app.use(compression({
  level: 6,
  threshold: 1024,
  filter: (req, res) => {
    if (req.headers['x-no-compression']) {
      return false;
    }
    return compression.filter(req, res);
  }
}));

app.get('/api/users', (req, res) => {
  const users = Array.from({ length: 1000 }, (_, i) => ({
    id: i,
    name: `User ${i}`,
    email: `user${i}@example.com`,
    bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'.repeat(5)
  }));
  res.json(users);
});

app.get('/health', (req, res) => {
  res.set('Cache-Control', 'no-transform');
  res.send('OK');
});

app.listen(3000, () => {
  console.log('Server with compression running on port 3000');
});

Use Cases

Pros & Cons

Pros

+Zero-configuration setup with sensible defaults works immediately for most Express applications
+Dramatic bandwidth reduction (60-85%) for text-based content translates to lower hosting costs and faster load times
+Intelligent filtering automatically skips small responses and incompressible content types
+Wide browser support since gzip and deflate are universally supported by all modern and legacy browsers
+Minimal CPU overhead for typical web applications makes it suitable for production use without performance concerns

Cons

−Real-time compression adds CPU overhead that may impact latency in extremely high-traffic scenarios or CPU-constrained environments
−Pre-compressed static files served via nginx or CDN are more efficient than on-demand compression for assets that don't change
−Brotli support requires explicit configuration and Node.js 11.7.0+ while competitors like koa-compress enable it by default
−Default threshold of 1KB may compress responses where the overhead exceeds the benefit, though this is configurable
−No built-in caching of compressed responses means the same content is recompressed on every request unless paired with caching middleware