💎 hono-compress

Compression plugin for Hono

Drop-in replacement of the built-in Compress Middleware, but with extra juice! 🍋

Features

• 💯 compress content with zstd, brotli, gzip, deflate
• ✨ ultra-fast and 100% type-safe
• 🚀 optimized for Bun
• 🎥 streaming response support
• 🌻 automatic encoding selection
• 🎯 customizable compression level and options
• 🎱 content size threshold and custom filtering
• 🔒 double-compression protection
• 🔥 fully documented and tested
• ☕ works flawlessy on Node, Deno, Cloudflare Workers, Deno Deploy and many edge runtimes

About

This project born as a fork of bun-compression, which itself is a fork of elysia-compression.

Both projects were broken, unmaintained and missing many of the features I was looking for, so I started with them, but ended up rewriting everything from scratch.

This project has been also inspired by hono/compress, expressjs/compression and elysia-compress.

Installation

bun add hono-compress

npm install hono-compress

pnpm add hono-compress

yarn add hono-compress

deno add hono-compress

Quick Start

import { Hono } from 'hono'
import { compress } from 'hono-compress'

const app = new Hono()

app.use(compress())

Usage

compress(options: HonoCompressOptions)

Creates a middleware function for compressing response content.

compress({
  encoding,
  encodings,
  fallback,
  force,
  strict,
  streaming,
  bun,
  node,
  threshold,
  zstdLevel,
  brotliLevel,
  gzipLevel,
  deflateLevel,
  zstdOptions,
  brotliOptions,
  gzipOptions,
  deflateOptions,
  filter,
})

Options

(optional) encoding: zstd | br | gzip | deflate

Defaults to undefined.

The encoding format to be used to compress the response content. Can be only one of the following (sorted in descending order by performance):

• zstd
• br
• gzip
• deflate

If not defined, all the formats declared in the option encodings can be used.

This option is provided primarily to maintain compatibility with hono/compress, use the option encodings to set the wanted compression formats.

(optional) encodings: (zstd | br | gzip | deflate)[]

Defaults to ['zstd', 'br', 'gzip', 'deflate'].

The encoding formats allowed to be used to compress the response content.

The first matching the request Accept-Encoding header according their order of declaration is chosen to compress the response content.

(optional) fallback: zstd | br | gzip | deflate

Defaults to undefined.

The encoding format to be used as fallback to compress the response content if no Accept-Encoding header is request by the client. If not defined, content will not be compressed.

(optional) force: boolean

Defaults to false.

Forces the content compression even if the response Content-Type header cannot be determined and the Cache-Control is set to no-transform.

(optional) strict: boolean

Defaults to true.

Complies with the client request directives. Disables the content compression if match the x-no-compression header.

(optional) streaming: boolean

Defaults to true.

Streams compressed content in chunked response.

Can be set to undefined to automatically detect when disable streaming compression. Enabled by default to always streaming content.

(optional) bun: boolean

Defaults to true.

Allows Bun stream compressor to be used if available.

(optional) node: boolean

Defaults to true.

Allows Node stream compressor to be used if available.

(optional) threshold: number

Defaults to 1024.

The minimum size in bytes for a response content to be compressed.

(optional) zstdLevel: number

Defaults to 2, min 1, max 22.

Zstandard algorithm compression level (format zstd).

(optional) brotliLevel: number

Defaults to 4, min 0, max 11.

Brotli algorithm compression level (format br).

(optional) gzipLevel: number

Defaults to 6, min 0, max 6.

Gzip algorithm compression level (format gzip).

(optional) deflateLevel: number

Defaults to 6, min 0, max 6.

Deflate algorithm compression level (format deflate).

(optional) zstdOptions: number

Defaults to undefined.

Zstandard algorithm compression options (format zstd).

Refer to the zstd manual for more details.

(optional) brotliOptions: object

Defaults to undefined.

Brotli algorithm compression options (format br).

Refer to the Brotli specification for more details.

(optional) gzipOptions: object

Defaults to undefined.

Gzip algorithm compression options (format gzip).

Refer to the zlib manual for more details.

(optional) deflateOptions: object

Defaults to undefined.

Deflate algorithm compression options (format deflate).

Refer to the zlib manual for more details.

(optional) filter: function

Defaults to undefined.

Optional function callback used to check if the response content should be compressed or not.

Overrides all the internal checks. Use with caution.

Parameters

• Hono Context

Return value

Boolean

Example

Force the response content to be always compressed:

import type { Context } from 'hono'

compress({
  filter: (c: Context) => true,
})