H3-compression

Handles compression for H3

Features

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

✔️  Stream Compression: You can use stream compressions (gzip, deflate and opt-in brotli / zstd)

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

✔️  h3 v1 & v2: Works with both h3 v1 and v2

✔️  Nuxt module: Drop h3-compression/nuxt into nuxt.config and configure it there

Install

# Using npm
npm install h3-compression

# Using yarn
yarn add h3-compression

# Using pnpm
pnpm add h3-compression

Usage (h3 v1)

import { createServer } from 'node:http'
import { createApp, eventHandler, toNodeListener } from 'h3'
import { useCompressionStream } from 'h3-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-compression'

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

listen(toNodeListener(app))

Usage (h3 v2)

In h3 v2 the response is an immutable web Response and the onBeforeResponse hook was removed. Use the compression / compressionStream middleware instead — they read the response returned by the next handler and replace it with a compressed one.

import { createServer } from 'node:http'
import { H3, toNodeHandler } from 'h3'
import { compression } from 'h3-compression'

const app = new H3()

app.use(compression()) // or app.use(compressionStream())
app.get('/', () => 'Hello world!')

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

You can also force a specific method (e.g. compression('gzip')) instead of detecting it from the Accept-Encoding header.

Brotli and stream compression

The native CompressionStream implements the WHATWG CompressionFormat enum, which only defines gzip, deflate and deflate-raw — there is no brotli format. This package therefore streams brotli through node:zlib instead, so it is available wherever node:zlib is (Node, and runtimes with node compatibility), but not on pure edge runtimes.

Because brotli is noticeably more CPU-expensive per request than gzip, it is never picked automatically. Turn it on with the brotli flag, or force it as the method:

app.use(compressionStream()) // gzip / deflate — unchanged default
app.use(compressionStream({ brotli: true })) // brotli, then gzip, then deflate
app.use(compressionStream('br')) // always brotli

The same flag works for the composable:

await useCompressionStream(event, response, { brotli: true })
// or explicitly
await useBrotliCompressionStream(event, response)

[!NOTE] The brotli stream is flushed per chunk (BROTLI_OPERATION_FLUSH) so that streamed responses stay streamed. With zlib's defaults brotli buffers the whole body until the source closes.

Zstd

Zstd is supported on both paths, and is opt-in for a different reason than brotli: node:zlib only gained zstd in Node 22.15.0 (and 23.8.0). Enabling it by default would make the negotiated Content-Encoding depend on the Node version the app happens to run on, which is a poor thing to discover in production. The package itself only requires Node >= 20.11.1, the same floor as h3.

app.use(compression({ zstd: true })) // zstd, then brotli, then gzip, then deflate
app.use(compressionStream({ zstd: true, brotli: true })) // same order, streamed

await useCompression(event, response, { zstd: true })

Behaviour on a runtime without zstd:

• with the zstd: true flag, zstd is skipped during negotiation and the next accepted encoding is used — no error, no special-casing needed in your code
• when forced (compression('zstd'), useZstdCompression), a TypeError naming the required Node version is thrown, because silently sending something else would be worse

Branch on it yourself with the exported predicate:

import { isZstdSupported } from 'h3-compression'

app.use(compression({ zstd: isZstdSupported() }))

Nuxt 3 & 4

Add the module and you're done — it wires the right Nitro hooks, skips Nuxt's internal routes and filters by content type for you:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['h3-compression/nuxt'],
})

Everything is configurable under the compression key:

export default defineNuxtConfig({
  modules: ['h3-compression/nuxt'],
  compression: {
    enabled: true,
    encoding: 'zlib', // or 'stream'
    brotli: false, // stream path only — zlib always prefers brotli
    zstd: false, // needs Node >= 22.15
    method: undefined, // force one method instead of negotiating
    contentTypes: ['text/', 'application/json', 'application/javascript', 'application/xml', 'image/svg+xml'],
    exclude: ['/_nuxt', '/__nuxt'],
    routeRules: true, // also compress cached (swr/isr) routes and /server/api
    threshold: 0, // skip bodies smaller than this many bytes
  },
})

| Option | Default | What it does | | --- | --- | --- | | enabled | true | Turn compression off without removing the module | | encoding | 'zlib' | 'zlib' buffers the body; 'stream' pipes it through a compression transform | | brotli | false | Consider brotli when negotiating. Only meaningful for 'stream' — the zlib path already prefers brotli | | zstd | false | Consider zstd when negotiating. Ignored on Node < 22.15, see Zstd | | method | – | Force one method instead of negotiating from Accept-Encoding | | contentTypes | text, JSON, JS, XML, SVG | Prefix match against Content-Type. Set to [] to compress everything | | exclude | ['/_nuxt', '/__nuxt'] | Path prefixes to skip. Compressing these breaks Nuxt's error page | | routeRules | true | Also attach to beforeResponse, which is what cached (swr/isr) routes and /server/api handlers go through | | threshold | 0 | Skip bodies below this size — under roughly a kilobyte compression makes payloads larger. Ignored for 'stream', where the size is not known up front |

[!NOTE] contentTypes and exclude replace the defaults rather than extending them. Spread the defaults in if you want to add to them.

Doing it manually

The module is a convenience wrapper — the hooks are still yours to wire if you want different behaviour per route:

server/plugins/compression.ts

import { useCompression } from 'h3-compression'

export default defineNitroPlugin((nitro) => {
  // Freshly rendered SSR pages.
  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)
  })

  // The `render:response` hook only runs for freshly rendered SSR pages.
  // Responses served from the Nitro route cache (`routeRules` with `swr` / `isr`)
  // and `/server/api` handlers go through `beforeResponse` instead.
  nitro.hooks.hook('beforeResponse', async (event, response) => {
    if (['/_nuxt', '/__nuxt'].some(prefix => event.path.startsWith(prefix)))
      return

    await useCompression(event, response)
  })
})

useCompression compresses string, Buffer/Uint8Array and JSON (object) bodies and skips everything else (e.g. streams), so binary assets are left untouched. If you only want to compress specific content types, guard on response.headers?.['content-type'] before calling it.

Utilities

H3-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)
• useZstdCompression(event, response)  – requires Node >= 22.15
• useCompression(event, response, options?)  – pass { zstd: true } to include zstd

Stream Compression

• useGZipCompressionStream(event, response)
• useDeflateCompressionStream(event, response)
• useBrotliCompressionStream(event, response)
• useZstdCompressionStream(event, response)  – requires Node >= 22.15
• useCompressionStream(event, response, options?)  – pass { brotli: true } / { zstd: true }

Middleware (h3 v2)

• compression(method | options?)  – middleware using zlib (brotli, gzip, deflate, opt-in zstd)
• compressionStream(method | options?)  – stream middleware (gzip, deflate, opt-in brotli / zstd)
• compressResponse(event, value, method?, options?)  – low-level helper returning a compressed Response
• compressResponseStream(event, value, method?, options?)  – low-level stream helper returning a compressed Response
• isZstdSupported()  – whether the runtime can compress with zstd

Nuxt

• h3-compression/nuxt  – the Nuxt module, configured under the compression key

Sponsors

Releated Projects

• H3

License

MIT License © 2023-PRESENT Gregor Becker