h3-fast-compression

Handles compression for H3

Features

✔️ Zlib Compression: You can use zlib compression (brotli, gzip and deflate)

✔️ Stream Compression: You can use native stream compressions (gzip, deflate)

✔️ Compression Detection: It uses the best compression which is accepted

✔️ Fast Compression: Much faster than h3-compression (see benchmark)

Install

# Using npm
npm install h3-fast-compression

# Using yarn
yarn add h3-fast-compression

# Using pnpm
pnpm add h3-fast-compression

Usage

import { createServer } from 'node:http'
import { createApp, eventHandler, toNodeListener } from 'h3'
import { useCompressionStream } from 'h3-fast-compression'

const app = createApp({ onBeforeResponse: useCompressionStream }) // or { onBeforeResponse: useCompression }
app.use(
  '/',
  eventHandler(() => 'Hello world!'),
)

createServer(toNodeListener(app)).listen(process.env.PORT || 3000)

Example using listhen for an elegant listener:

import { createApp, eventHandler, toNodeListener } from 'h3'
import { listen } from 'listhen'
import { useCompressionStream } from 'h3-fast-compression'

const app = createApp({ onBeforeResponse: useCompressionStream }) // or { onBeforeResponse: useCompression }
app.use(
  '/',
  eventHandler(() => 'Hello world!'),
)

listen(toNodeListener(app))

Nuxt 3

If you want to use it in nuxt 3 you can define a nitro plugin.

server/plugins/compression.ts

import { useCompression } from 'h3-fast-compression'

export default defineNitroPlugin((nitro) => {
  nitro.hooks.hook('render:response', async (response, { event }) => {
    if (!response.headers?.['content-type']?.startsWith('text/html'))
      return

    await useCompression(event, response)
  })
})

[!NOTE]
useCompressionStream doesn't work right now in nitro. So you just can use useCompression

Utilities

h3-fast-compression has a concept of composable utilities that accept event (from eventHandler((event) => {})) as their first argument and response as their second.

Zlib Compression

useGZipCompression(event, response)
useDeflateCompression(event, response)
useBrotliCompression(event, response)
useCompression(event, response)

Stream Compression

useGZipCompressionStream(event, response)
useDeflateCompressionStream(event, response)
useCompressionStream(event, response)

Benchmarks

For reference, several compression algorithms were tested and compared on a desktop featuring a Core i7-11370H CPU and running Ubuntu 24.04. Input is the document of amazon.fr (150kB). Compression ratio is uncompressed size / compressed size, more is better (smaller output).

Compress method	Ratio	Timing
h3-fast-compression brotli	7.39	14ms
h3-compression brotli	9.08	1240ms
gzip	6.82	16ms
deflate	6.82	16ms

Although the h3-fast-compression brotli header loses some compression ratio, it is much faster and therefore more suitable for dynamic content.

Detalhes do pacote