{"id":17084,"library":"compression-next","title":"Node.js Compression Middleware with Brotli Support","description":"compression-next is a Node.js middleware designed for compressing HTTP responses, offering support for `deflate`, `gzip`, and `brotli` encodings. Currently at version 1.0.3, this package originated as a pragmatic fork to provide immediate `brotli` compression functionality, addressing a long-standing feature request within the `expressjs/compression` project. Its release cadence is reactive, likely responding to updates in Node.js's native `zlib` module or the upstream `expressjs/compression` project. A primary differentiator is its readily available `brotli` support, a feature not present in the mainstream `expressjs/compression` at the time of its inception. Developers using this library should be aware of its temporary nature, with the expectation to transition back to the core `expressjs/compression` once `brotli` is officially integrated there. It integrates seamlessly with popular Node.js web frameworks like Express.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/Econify/compression-next","tags":["javascript"],"install":[{"cmd":"npm install compression-next","lang":"bash","label":"npm"},{"cmd":"yarn add compression-next","lang":"bash","label":"yarn"},{"cmd":"pnpm add compression-next","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used by the default filter function to determine if a response's Content-Type should be compressed.","package":"compressible","optional":false}],"imports":[{"note":"The package exports the middleware function as its default export for ESM.","wrong":"import { compression } from 'compression-next';","symbol":"default export (middleware function)","correct":"import compression from 'compression-next';"},{"note":"Standard CommonJS import for Node.js environments.","symbol":"CommonJS export","correct":"const compression = require('compression-next');"},{"note":"The default filter function is exposed as a property on the middleware function, allowing custom filter logic to leverage the default behavior.","symbol":"filter utility","correct":"import compression from 'compression-next'; const customFilter = (req, res) => compression.filter(req, res);"}],"quickstart":{"code":"import express from 'express';\nimport compression from 'compression-next';\nimport { Z_BEST_COMPRESSION, constants } from 'zlib'; // Import zlib constants for options\n\nconst app = express();\nconst port = 3000;\n\n// Apply compression middleware\napp.use(compression({\n  // For gzip/deflate, use 'level' option\n  level: Z_BEST_COMPRESSION, // Example: apply best gzip/deflate compression\n  // For brotli specific parameters, use 'params'\n  // params: {\n  //   [constants.BROTLI_PARAM_MODE]: constants.BROTLI_MODE_TEXT,\n  //   [constants.BROTLI_PARAM_QUALITY]: constants.BROTLI_MAX_QUALITY\n  // },\n  filter: (req, res) => {\n    if (req.headers['x-no-compression']) {\n      // Example: Do not compress responses with a specific header\n      return false;\n    }\n    // Fallback to the default filter function (which uses 'compressible' module)\n    return compression.filter(req, res);\n  }\n}));\n\n// Route for a simple text response\napp.get('/', (req, res) => {\n  res.send('Hello World! This response should be compressed.');\n});\n\n// Route for a larger JSON response to better demonstrate compression effect\napp.get('/data', (req, res) => {\n  const largeData = Array(500).fill({ id: Math.random(), value: 'some repetitive text here for good compression effect and larger payload size to showcase middleware functionality.' });\n  res.json(largeData);\n});\n\napp.listen(port, () => {\n  console.log(`Server listening at http://localhost:${port}`);\n  console.log('Test with curl -H \"Accept-Encoding: gzip, deflate, br\" http://localhost:3000/data');\n  console.log('And without: curl http://localhost:3000/data');\n});","lang":"typescript","description":"This quickstart demonstrates how to integrate `compression-next` with an Express application, applying compression to HTTP responses. It shows basic usage with options like compression level and a custom filter."},"warnings":[{"fix":"Ensure your Node.js environment is at least v11.7.0 or v10.16.0 to leverage Brotli compression. Refer to 'engines' field in package.json.","message":"Brotli compression is only supported on Node.js versions v11.7.0 and v10.16.0 or newer. Attempts to use Brotli on older Node.js versions will result in an error or fallback to Gzip/Deflate if client supports it.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Monitor the `expressjs/compression` repository for Brotli integration. Once available, plan to migrate your application to the official package for long-term stability and maintenance.","message":"This package is a temporary fork. It's intended to be used until Brotli support is merged into the upstream `expressjs/compression` library. Developers should plan for a future migration back to the official package.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If compression is desired, ensure that the `Cache-Control` header does not include `no-transform`. Adjust server or proxy configurations if this header is being set unintentionally.","message":"Responses containing a `Cache-Control` header with the `no-transform` directive will not be compressed by this middleware. This is by design, adhering to HTTP caching standards.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always set an appropriate `Content-Type` header for your responses. For custom compression logic, provide your own `filter` function in the middleware options.","message":"The default `filter` function relies on the response's `Content-Type` header and the `compressible` module to decide whether to compress. If the `Content-Type` is missing or indicates an incompressible type, the response will not be compressed.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ESM, use `import compression from 'compression-next';`. For CommonJS, use `const compression = require('compression-next');`. Do not use named imports like `import { compression } from 'compression-next';`.","cause":"Incorrect import statement or attempting to destructure a default export.","error":"TypeError: Cannot read properties of undefined (reading 'filter') or compression is not a function"},{"fix":"Upgrade Node.js to v11.7.0 / v10.16.0 or newer. Verify the client's `Accept-Encoding` header includes 'br'. Ensure the response `Content-Type` is recognized as compressible or provide a custom `filter` function.","cause":"Node.js version is too old, client does not support Brotli (missing 'br' in Accept-Encoding header), or the response content type is deemed incompressible.","error":"Brotli compression not applied / Response not compressed with 'br' encoding"},{"fix":"Inspect HTTP response headers for `Cache-Control: no-transform`. Check `res.getHeader('Content-Type')` to ensure it's a compressible type. Debug any custom `filter` function logic to ensure it returns `true` when compression is desired.","cause":"The default `filter` function blocked compression, `Cache-Control: no-transform` header was present, or a custom `filter` returned `false`.","error":"Response body is not compressed despite `compression-next` being active in Express"}],"ecosystem":"npm","meta_description":null}