@fastify/compress

The plugin provides two main functionalities: a compression utility added to the Fastify reply object and a global hook for decompressing request payloads.

It supports the following encoding tokens, selected in this priority order based on the accept-encoding header:

1. zstd (Requires Node.js 22.15+/23.8+)
2. br (Brotli)
3. gzip
4. deflate
5. * (Defaults to gzip)
6. identity (No compression)

Compression is applied based on the content-type. If no content type is specified, it defaults to application/json.

Note: For large-scale production environments, it is recommended to use a proxy like Nginx to handle response compression instead of the application layer.

Install the plugin using npm to add compression utilities to the Fastify reply object and decompression hooks for request payloads.

npm i @fastify/compress

Use the onUnsupportedEncoding(encoding, request, reply) option to define a custom error response when a client requests an encoding that the server does not support. The function can return a string | Buffer | Stream | Error payload.

await fastify.register(
  import('@fastify/compress'),
  {
    onUnsupportedEncoding: (encoding, request, reply) => {
      reply.code(406)
      return 'We do not support the ' + encoding + ' encoding.'
    }
  }
)

By default, compression is determined by mime-db. You can extend this by providing a Regular Expression or a function to the customTypes option to include additional content types.

// Using a Regex
await fastify.register(
  import('@fastify/compress'),
  { customTypes: /x-protobuf$/ }
)

// Using a function
await fastify.register(
  import('@fastify/compress'),
  { customTypes: contentType => contentType.endsWith('x-protobuf') }
)

Set the threshold option to define the minimum byte size required for a response to be compressed. The default is 1024 bytes.

await fastify.register(
  import('@fastify/compress'),
  { threshold: 2048 }
)

You can override global compression settings for specific routes using the compress key in the route configuration. Setting compress: false on a route will explicitly disable compression for that route, even if global compression is active.

// Only compress if the payload is above a certain size and use custom zlib settings
fastify.get('/custom-route', {
  compress: {
    inflateIfDeflated: true,
    threshold: 128,
    zlib: {
      createBrotliCompress: () => createYourBrotliCompress(),
      createGzip: () => createYourGzip(),
      createDeflate: () => createYourDeflate()
    }
  }
}, (req, reply) => {
  // ...
})

Customize the error response for unsupported or invalid request encodings using these options:

• onUnsupportedRequestEncoding(request, encoding): Returns an error when the client sends an encoding not in your allowed list.
• onInvalidRequestPayload(request, encoding, error): Returns an error when the payload cannot be successfully decompressed.

await fastify.register(
  import('@fastify/compress'),
  {
    onUnsupportedRequestEncoding: (request, encoding) => {
      return { 
        statusCode: 415, 
        code: 'UNSUPPORTED', 
        error: 'Unsupported Media Type', 
        message: 'We do not support the ' + encoding + ' encoding.' 
      }
    }
  }
)

Control which compression algorithms are used and their priority by passing an array of tokens to the encodings option.

// Only support gzip and deflate, with deflate preferred
await fastify.register(
  import('@fastify/compress'),
  { encodings: ['deflate', 'gzip'] }
)

// Example with zstd support (Node.js 22.15+/23.8+)
await fastify.register(
  import('@fastify/compress'),
  { encodings: ['zstd', 'br', 'gzip'] }
)

Pass native Node.js zlib options to brotliOptions and zlibOptions to fine-tune compression quality and parameters.

server.register(fastifyCompress, {
  brotliOptions: {
    params: {
      [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
      [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
    },
  },
  zlibOptions: {
    level: 6,
  }
});