Response Compression Plugin

Compress response bodies on the server and decompress them on the client to reduce bandwidth usage and improve performance.

Server

Use ResponseCompressionHandlerPlugin to compress response bodies. The plugin selects an encoding based on Accept-Encoding header:

import { ResponseCompressionHandlerPlugin } from '@orpc/server/plugins'

const handler = new RPCHandler(router, {
  plugins: [
    new ResponseCompressionHandlerPlugin({
      /**
       * The compression schemes to use for response compression.
       * Schemes are prioritized by their order in this array and
       * only applied if the client supports them.
       * Supported values: 'gzip' | 'deflate' | 'deflate-raw'
       *
       * @default ['gzip', 'deflate']
       */
      encodings: ['gzip', 'deflate'],

      /**
       * The minimum response size in bytes required to trigger compression.
       * Responses smaller than this threshold will not be compressed to avoid overhead.
       * If the response size cannot be determined, compression will still be applied.
       *
       * @default 1024 (1KB)
       */
      threshold: 1024,
    }),
  ],
})

Customize Compressible Content Types

For binary transfers (streams, files, and file form-data parts), the plugin only compresses content types that benefit from compression. Override the check with isCompressibleContentType:

import { ResponseCompressionHandlerPlugin } from '@orpc/server/plugins'

const handler = new RPCHandler(router, {
  plugins: [
    new ResponseCompressionHandlerPlugin({
      /**
       * Also receives the routing interceptor options for per-request decisions.
       *
       * @default isCompressibleContentType (covers common text-based formats)
       */
      isCompressibleContentType: (contentType, { request }) => {
        return /^application\/x-custom-format(?:[;\s]|$)/i.test(contentType ?? '') && request.headers['x-no-compression'] === undefined
      },
    }),
  ],
})

Client

Use ResponseCompressionLinkPlugin to advertise supported encodings via Accept-Encoding header and automatically decompress response bodies based on the Content-Encoding header:

import { ResponseCompressionLinkPlugin } from '@orpc/client/plugins'

const link = new RPCLink({
  plugins: [
    new ResponseCompressionLinkPlugin({
      /**
       * Compression schemes to advertise via Accept-Encoding, in preference order.
       * Supported values: 'gzip' | 'deflate' | 'deflate-raw'
       *
       * @default ['gzip', 'deflate']
       */
      encodings: ['gzip', 'deflate'],
    }),
  ],
})

Learn More

For implementation details, see the ResponseCompressionLinkPlugin source code or the ResponseCompressionHandlerPlugin source code.