Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js zlib.brotliCompress() method

Reference for zlib.brotliCompress(), brotliDecompress(), their sync forms and createBrotliCompress() in Node.js: quality, mode and window parameters, with examples.

Brotli is a general-purpose compression format that usually beats gzip by 15 to 25 percent on text, especially HTML, CSS, JavaScript and JSON, and is supported by all modern browsers through Content-Encoding: br. Node exposes it in node:zlib as brotliCompress() and brotliDecompress() (callback style), brotliCompressSync() and brotliDecompressSync() (blocking style) and the stream factories createBrotliCompress() and createBrotliDecompress().

Brotli is configured differently from gzip. Instead of level and friends, you pass a params object whose keys are numeric constants from zlib.constants, such as BROTLI_PARAM_QUALITY.

NODE
import { brotliCompressSync, brotliDecompressSync } from 'node:zlib';

const packed = brotliCompressSync('hello hello hello');
console.log(brotliDecompressSync(packed).toString());

Try it

Node.js Quality and size

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Async form, errors and limits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
zlib.brotliCompress(buffer, options?, callback: (err, result: Buffer) => void): void
zlib.brotliDecompress(buffer, options?, callback): void
zlib.brotliCompressSync(buffer, options?): Buffer
zlib.brotliDecompressSync(buffer, options?): Buffer
zlib.createBrotliCompress(options?): BrotliCompress
zlib.createBrotliDecompress(options?): BrotliDecompress
Name Description
buffer A string, Buffer, typed array, DataView or ArrayBuffer.
options.params An object mapping zlib.constants.BROTLI_PARAM_* numbers to values.
options.chunkSize Size of internal output chunks. Default 16384.
options.maxOutputLength Maximum output size in bytes for the buffer helpers. Exceeding it throws ERR_BUFFER_TOO_LARGE.
options.flush, options.finishFlush Flush behavior; see zlib options.

Common params keys:

Constant Meaning
BROTLI_PARAM_QUALITY 0 to 11. Default 11 (smallest output, slowest).
BROTLI_PARAM_MODE BROTLI_MODE_GENERIC (default), BROTLI_MODE_TEXT or BROTLI_MODE_FONT.
BROTLI_PARAM_LGWIN Log2 of the window size, 10 to 24. Default 22.
BROTLI_PARAM_SIZE_HINT The expected input size in bytes, if known. Lets the encoder choose better settings.

Returns: a Buffer for the sync forms, nothing for the callback forms, a Transform stream for the create* factories.

Errors: corrupt input fails with an error whose code comes straight from the Brotli decoder (for example ERR__ERROR_FORMAT_PADDING_1); invalid parameters throw ERR_BROTLI_INVALID_PARAM (from params) or ERR_INVALID_ARG_TYPE.

Usage notes

  • Quality 11 is the default and is very slow, often tens of times slower than quality 4 to 6. For on-the-fly HTTP responses use 4 or 5; reserve 11 for assets compressed once at build time.
  • Decompression speed is similar to gzip at any quality, so a higher quality only costs time when compressing.
  • There is no level option and no dictionary; passing gzip-style options has no effect on Brotli.
  • BROTLI_MODE_TEXT helps UTF-8 text slightly and BROTLI_MODE_FONT suits WOFF2-like data. Leave it at the default when unsure.
  • Browsers only advertise br over HTTPS, so test with a secure origin or an explicit Accept-Encoding header.
  • Decompress untrusted data with maxOutputLength; see Decompression bombs.
  • Brotli has no checksum of its own, so detect corruption at a higher level when it matters.