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 & 4

If you want to use it in Nuxt 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 }) => {
    // Skip internal nuxt routes (e.g. error page)
    if (['/_nuxt', '/__nuxt'].some(prefix => getRequestURL(event).pathname.startsWith(prefix)))
      return

    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.

Related Projects

• H3
• H3 Compression

License

MIT License © 2023-PRESENT Timothée Gonnet