Registry / http-networking / http-compression

http-compression

library1.1.3jsnpmunverified

http-compression is a lightweight Node.js library designed to add Gzip and Brotli compression capabilities to HTTP servers. Currently at stable version 1.1.3, it primarily functions as Express-style middleware but can also be integrated directly with Node.js's `http.createServer` primitives. The project maintains a steady, albeit infrequent, release cadence, with recent updates focused on dependency maintenance and minor feature enhancements. Key differentiators include its extremely small footprint (< 1kB) with no external dependencies, automatic detection of the best compression encoding (Gzip or Brotli) based on the `Accept-Encoding` header, and configurable compression levels, response size thresholds, and MIME type filtering. It requires Node.js version 18 or greater.

http-networking web-framework

npm install http-compression

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-COMPRESSION

http-compression

http-networkingjavascriptv1.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

compression

✓ import compression from 'http-compression';

✗ import { compression } from 'http-compression';

The package exports its main factory function as the default export. This function is called with options to create the middleware.

compression

✓ const compression = require('http-compression');

✗ const { compression } = require('http-compression');

For CommonJS environments, the factory function is directly exported via `module.exports`.

Demonstrates how to integrate `http-compression` with a native Node.js HTTP server, applying custom compression settings for responses larger than a specified threshold.

import compression from 'http-compression'; import { createServer } from 'http'; const compressMiddleware = compression({ threshold: 500, // Compress responses larger than 500 bytes level: { brotli: 5, gzip: 5 }, // Custom compression levels mimes: /text|json/i // Only compress text and JSON }); const server = createServer((req, res) => { compressMiddleware(req, res, () => { // Simulate a large text response res.setHeader('Content-Type', 'text/plain'); res.end('hello world!'.repeat(100)); // Make sure content is > threshold }); }); server.listen(3000, () => { console.log('> Server listening at http://localhost:3000'); console.log('> Try fetching a large text response and observe Content-Encoding header.'); });

Debug

Known issues

breakingThe `level` option for compression configuration was changed from accepting a single number to requiring an object containing `brotli` and `gzip` level properties.

fix

Update your `level` option from a number (e.g., `level: 1`) to an object (e.g., `level: { brotli: 1, gzip: 1 }`).

affects: >=1.1.0

gotchaThe package explicitly requires Node.js version 18 or higher. Running on older Node.js versions will result in an error or unexpected behavior.

fix

Ensure your Node.js environment is version 18 or greater. Upgrade Node.js if necessary.

affects: *

gotchaResponses below the configured `threshold` (defaulting to 1024 bytes) will not be compressed. This is to avoid diminishing returns for very small payloads.

fix

If content is not being compressed, check the response body size. Adjust the `threshold` option if you need to compress smaller responses, e.g., `compression({ threshold: 0 })`.

affects: *

gotchaCompression is only applied to response `Content-Type` headers that match the `mimes` regular expression (default: `/text|javascript|\/json|xml/i`). Binary content is typically excluded.

fix

Verify the `Content-Type` header of the response. If you need to compress additional MIME types, customize the `mimes` option: `compression({ mimes: /text|javascript|\/json|xml|image\/svg\+xml/i })`.

affects: *

Errors

Common errors & fixes

TypeError: compression is not a function

Attempting to use `http-compression` as a named import or directly calling it without first importing the default export.

fix

Use `import compression from 'http-compression';` for ESM or `const compression = require('http-compression');` for CommonJS to correctly obtain the factory function.

Error: The 'options.level' property must be an object with 'brotli' and 'gzip' keys.

Passing a number directly to the `level` option, which was deprecated and changed in v1.1.0.

fix

Update the `level` option to be an object, e.g., `level: { brotli: 1, gzip: 1 }`. Refer to the API documentation for valid ranges for each algorithm.

Response does not have Content-Encoding header set to 'gzip' or 'br'

Compression is not being applied due to the response falling below the `threshold`, having an unsupported `mimes` type, or the client not sending an `Accept-Encoding` header.

fix

Check the response size (must be greater than `threshold`), the `Content-Type` header (must match `mimes`), and ensure the client sends `Accept-Encoding: gzip, deflate, br` header in the request.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Kikobeats/http-compression ↗

packagehttps://www.npmjs.com/package/http-compression ↗