{"id":12911,"library":"brotli-wasm","title":"Brotli WebAssembly Compressor","description":"brotli-wasm is a JavaScript/TypeScript library providing Brotli compression and decompression capabilities across both Node.js (v18 and above) and browser environments, powered by WebAssembly. It wraps the well-regarded Rust Brotli crate (currently v5 as of `brotli-wasm` v3.x), compiling it to WASM for broad compatibility. The current stable version is 3.0.1, with major version updates occurring when significant breaking changes are introduced, such as API overhauls or minimum engine version bumps. A key differentiator is its consistent, battle-tested API that abstracts away the complexities of WASM loading and environment-specific implementations, allowing developers to use a single codebase for compression needs in diverse JavaScript runtimes. It offers both a simple `compress`/`decompress` API for buffers and advanced `CompressStream`/`DecompressStream` classes for streaming data, making it suitable for various use cases from file processing to network communication. It explicitly states no runtime dependencies.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/httptoolkit/brotli-wasm","tags":["javascript","brotli","wasm","compression","decompression","typescript"],"install":[{"cmd":"npm install brotli-wasm","lang":"bash","label":"npm"},{"cmd":"yarn add brotli-wasm","lang":"bash","label":"yarn"},{"cmd":"pnpm add brotli-wasm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The default export is a Promise in browser environments, which must be awaited before use. In Node.js, it can often be used synchronously but awaiting is recommended for consistent cross-environment code.","wrong":"const brotli = require('brotli-wasm');","symbol":"default (brotliPromise)","correct":"import brotliPromise from 'brotli-wasm';"},{"note":"The `compress` and `decompress` methods are properties of the resolved module after the `brotliPromise` has settled, not direct named exports from the package.","wrong":"import { compress } from 'brotli-wasm';","symbol":"compress, decompress","correct":"const { compress, decompress } = await brotliPromise;"},{"note":"These classes are named exports available directly from the module for advanced streaming operations. They can be imported directly in ESM contexts.","wrong":"const { CompressStream } = brotliPromise;","symbol":"CompressStream, DecompressStream","correct":"import { CompressStream, DecompressStream } from 'brotli-wasm';"}],"quickstart":{"code":"import brotliPromise from 'brotli-wasm';\n\nconst runExample = async () => {\n  const brotli = await brotliPromise; // Import is async in browsers due to wasm requirements!\n\n  const textEncoder = new TextEncoder();\n  const textDecoder = new TextDecoder();\n\n  const input = 'some input data for brotli compression and decompression demonstration. This string is long enough to show a realistic use case.';\n\n  const uncompressedData = textEncoder.encode(input);\n  const compressedData = brotli.compress(uncompressedData);\n  const decompressedData = brotli.decompress(compressedData);\n\n  console.log('Original size:', uncompressedData.byteLength, 'bytes');\n  console.log('Compressed size:', compressedData.byteLength, 'bytes');\n  console.log('Decompressed data:', textDecoder.decode(decompressedData));\n};\n\nrunExample();","lang":"typescript","description":"Demonstrates asynchronous loading and basic Brotli compression/decompression in a browser-compatible environment using `TextEncoder` and `TextDecoder`."},"warnings":[{"fix":"Upgrade your Node.js environment to v18.0.0 or higher.","message":"Version 3.0.0 updated the minimum supported Node.js engine to v18. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Thoroughly test existing Brotli compressed data and new compression results after upgrading to v3.0.0 to ensure compatibility and expected behavior.","message":"Version 3.0.0 updated the underlying Rust Brotli crate from v3.3 to v5. While no API changes are expected, subtle behavioral differences in compression or decompression might occur (YMMV).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Refactor code using `CompressStream` and `DecompressStream` to retrieve output data and status from the result object returned by `compress()`/`decompress()` methods, rather than querying stream state directly.","message":"In version 2.0.0, the Streams API (`CompressStream`, `DecompressStream`) underwent significant changes. Methods like `result()` and `last_input_offset()` were removed. The `compress()` and `decompress()` methods now return a result object containing `buf`, `code`, and `in` properties, instead of just a buffer.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Always use `await brotliPromise` or `await import('brotli-wasm').then(m => m.default)` to ensure the WebAssembly module is loaded and initialized before attempting to use its functions.","message":"When importing `brotli-wasm` in a browser environment or using a bundler, the default export is a Promise that must be awaited before the `compress` and `decompress` functions become available.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the default export is awaited: `const brotli = await brotliPromise;` or `const brotli = await import('brotli-wasm').then(m => m.default);`","cause":"Attempting to call `compress` or `decompress` on the `brotli-wasm` default export (which is a Promise in some environments) before it has resolved.","error":"TypeError: brotli.compress is not a function"},{"fix":"In browser environments, use `TextEncoder` and `TextDecoder` for converting strings to/from `Uint8Array`, or include a `Buffer` polyfill like `browserify-zlib` if `Buffer` is strictly required.","cause":"Using `Buffer.from()` or other Node.js `Buffer` APIs directly in a browser environment without a polyfill.","error":"ReferenceError: Buffer is not defined"},{"fix":"Use ES Module `import brotliPromise from 'brotli-wasm';` and ensure your bundler (Webpack, Vite, Rollup) or Node.js environment is configured to handle ES Modules and WebAssembly correctly.","cause":"Trying to use CommonJS `require()` syntax to import `brotli-wasm` in an environment configured for pure ES Modules, or expecting synchronous `require` behavior in a browser context where only async ESM is supported for WASM.","error":"require() of ES Module ... is not supported."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}