{"id":13309,"library":"http-compression","title":"HTTP Compression Middleware","description":"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.","status":"active","version":"1.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/Kikobeats/http-compression","tags":["javascript","br","brotli","compress","compression","deflate","gzip","http","server"],"install":[{"cmd":"npm install http-compression","lang":"bash","label":"npm"},{"cmd":"yarn add http-compression","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-compression","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports its main factory function as the default export. This function is called with options to create the middleware.","wrong":"import { compression } from 'http-compression';","symbol":"compression","correct":"import compression from 'http-compression';"},{"note":"For CommonJS environments, the factory function is directly exported via `module.exports`.","wrong":"const { compression } = require('http-compression');","symbol":"compression","correct":"const compression = require('http-compression');"}],"quickstart":{"code":"import compression from 'http-compression';\nimport { createServer } from 'http';\n\nconst compressMiddleware = compression({\n  threshold: 500, // Compress responses larger than 500 bytes\n  level: { brotli: 5, gzip: 5 }, // Custom compression levels\n  mimes: /text|json/i // Only compress text and JSON\n});\n\nconst server = createServer((req, res) => {\n  compressMiddleware(req, res, () => {\n    // Simulate a large text response\n    res.setHeader('Content-Type', 'text/plain');\n    res.end('hello world!'.repeat(100)); // Make sure content is > threshold\n  });\n});\n\nserver.listen(3000, () => {\n  console.log('> Server listening at http://localhost:3000');\n  console.log('> Try fetching a large text response and observe Content-Encoding header.');\n});","lang":"javascript","description":"Demonstrates how to integrate `http-compression` with a native Node.js HTTP server, applying custom compression settings for responses larger than a specified threshold."},"warnings":[{"fix":"Update your `level` option from a number (e.g., `level: 1`) to an object (e.g., `level: { brotli: 1, gzip: 1 }`).","message":"The `level` option for compression configuration was changed from accepting a single number to requiring an object containing `brotli` and `gzip` level properties.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Ensure your Node.js environment is version 18 or greater. Upgrade Node.js if necessary.","message":"The package explicitly requires Node.js version 18 or higher. Running on older Node.js versions will result in an error or unexpected behavior.","severity":"gotcha","affected_versions":"*"},{"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 })`.","message":"Responses below the configured `threshold` (defaulting to 1024 bytes) will not be compressed. This is to avoid diminishing returns for very small payloads.","severity":"gotcha","affected_versions":"*"},{"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 })`.","message":"Compression 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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `import compression from 'http-compression';` for ESM or `const compression = require('http-compression');` for CommonJS to correctly obtain the factory function.","cause":"Attempting to use `http-compression` as a named import or directly calling it without first importing the default export.","error":"TypeError: compression is not a function"},{"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.","cause":"Passing a number directly to the `level` option, which was deprecated and changed in v1.1.0.","error":"Error: The 'options.level' property must be an object with 'brotli' and 'gzip' keys."},{"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.","cause":"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.","error":"Response does not have Content-Encoding header set to 'gzip' or 'br'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}