@fastify/compress is a comprehensive Fastify plugin that provides HTTP response compression and request decompression capabilities. It supports multiple compression algorithms including gzip, deflate, brotli, and zstd, with intelligent algorithm selection based on client Accept-Encoding headers and configurable compression thresholds.
npm install @fastify/compressconst fastifyCompress = require('@fastify/compress');ESM support:
import fastifyCompress from '@fastify/compress';const fastify = require('fastify')({ logger: true });
// Register the plugin with global compression
await fastify.register(fastifyCompress, {
global: true,
encodings: ['gzip', 'deflate', 'br'],
threshold: 1024
});
// Routes will automatically compress responses > 1024 bytes
fastify.get('/data', async (request, reply) => {
return { large: 'data'.repeat(1000) };
});
// Manual compression using reply.compress
fastify.get('/manual', async (request, reply) => {
const data = { message: 'Hello World' };
reply.compress(data);
});
await fastify.listen({ port: 3000 });@fastify/compress integrates deeply with Fastify's lifecycle through several key components:
reply.compress() method for manual compression control// Fastify lifecycle hooks used by @fastify/compress
const LIFECYCLE_HOOKS = {
// onRoute: Configures per-route compression/decompression settings
onRoute: 'Merges global and route-specific options during route registration',
// onRequest: Decorates reply object with compress method
onRequest: 'Adds reply.compress() method for manual compression',
// preParsing: Handles automatic request decompression
preParsing: 'Decompresses request payload based on Content-Encoding header',
// onSend: Handles automatic response compression
onSend: 'Compresses response payload based on Accept-Encoding header'
};Core plugin setup with global compression and decompression settings, encoding preferences, and custom content-type matching.
function fastifyCompress(
fastify: FastifyInstance,
options: FastifyCompressOptions,
next: (err?: Error) => void
): void;
interface FastifyCompressOptions {
global?: boolean;
encodings?: EncodingToken[];
threshold?: number;
customTypes?: RegExp | CompressibleContentTypeFunction;
brotliOptions?: BrotliOptions;
zlibOptions?: ZlibOptions;
removeContentLengthHeader?: boolean;
inflateIfDeflated?: boolean;
onUnsupportedEncoding?: (encoding: string, request: FastifyRequest, reply: FastifyReply) => string | Buffer | Stream;
requestEncodings?: EncodingToken[];
forceRequestEncoding?: EncodingToken;
onUnsupportedRequestEncoding?: (encoding: string, request: FastifyRequest) => Error | undefined | null;
onInvalidRequestPayload?: (encoding: string, request: FastifyRequest, error: Error) => Error | undefined | null;
zlib?: unknown;
}Automatic and manual response compression with content-type filtering, algorithm selection, and custom compression thresholds.
// Reply decoration
interface FastifyReply {
compress(payload: CompressiblePayload): void;
}
type Input =
| Buffer
| NodeJS.TypedArray
| ArrayBuffer
| string
| Iterable<Buffer | string>
| AsyncIterable<Buffer | string>;
type CompressiblePayload = Input | Stream;Automatic decompression of compressed request payloads with support for multiple encoding algorithms and error handling.
// Route-level decompression configuration
interface RouteDecompressOptions {
forceRequestEncoding?: EncodingToken;
onInvalidRequestPayload?: (encoding: string, request: FastifyRequest, error: Error) => Error | undefined | null;
onUnsupportedRequestEncoding?: (encoding: string, request: FastifyRequest) => Error | undefined | null;
requestEncodings?: EncodingToken[];
zlib?: unknown;
}type EncodingToken = 'zstd' | 'br' | 'gzip' | 'deflate' | 'identity';
type CompressibleContentTypeFunction = (contentType: string) => boolean;
// Route-level compression options
type RouteCompressOptions = Pick<FastifyCompressOptions,
| 'brotliOptions'
| 'customTypes'
| 'encodings'
| 'inflateIfDeflated'
| 'onUnsupportedEncoding'
| 'removeContentLengthHeader'
| 'threshold'
| 'zlib'
| 'zlibOptions'
>;
interface BrotliOptions {
params?: {
[key: number]: number;
};
}
interface ZlibOptions {
flush?: number;
finishFlush?: number;
chunkSize?: number;
windowBits?: number;
level?: number;
memLevel?: number;
strategy?: number;
dictionary?: Buffer | NodeJS.TypedArray | DataView | ArrayBuffer;
}The plugin uses several important constants and default values:
// Default compression threshold (bytes)
const DEFAULT_THRESHOLD = 1024;
// Default compressible content types (regex)
const DEFAULT_COMPRESSIBLE_TYPES = /^text\/(?!event-stream)|(?:\+|\/)json(?:;|$)|(?:\+|\/)text(?:;|$)|(?:\+|\/)xml(?:;|$)|octet-stream(?:;|$)/u;
// Default Brotli compression quality
const DEFAULT_BROTLI_QUALITY = 4;
// gzip alias patterns in Accept-Encoding headers
const GZIP_ALIAS_PATTERN = /\*|x-gzip/gu;
// Plugin metadata
const PLUGIN_NAME = '@fastify/compress';
const FASTIFY_VERSION = '5.x';The plugin defines custom error classes for compression-related failures:
// Error codes
const ERROR_CODES = {
INVALID_CONTENT_ENCODING: 'FST_CP_ERR_INVALID_CONTENT_ENCODING',
INVALID_CONTENT: 'FST_CP_ERR_INVALID_CONTENT'
};
class InvalidRequestEncodingError extends Error {
name: 'FastifyCompressError';
code: 'FST_CP_ERR_INVALID_CONTENT_ENCODING';
statusCode: 415;
message: 'Unsupported Content-Encoding: {encoding}';
}
class InvalidRequestCompressedPayloadError extends Error {
name: 'FastifyCompressError';
code: 'FST_CP_ERR_INVALID_CONTENT';
statusCode: 400;
message: 'Could not decompress the request payload using the provided encoding';
}