Picture this: your single-page app ships a 320 KB Brotli-compressed JavaScript bundle, you redeploy every Tuesday, and every returning user re-downloads almost the entire payload — even when only 4% of the code actually changed. Painful, right? Compression Dictionaries Transport, finalized as an IETF specification in late 2024 and shipping by default in Chrome 123+ (with Edge and the stable Chromium derivatives now aligned in 2026), pretty much eliminates that waste.
In production tests on a real React app I help maintain, weekly-deploy bundle transfers dropped from 312 KB to 26 KB. That's a 92% reduction with zero JavaScript code changes. Honestly, it was the rare web-perf win that felt like cheating.
So, let's dive in. This guide covers what the feature actually does, the exact HTTP headers and CDN setup you need, the two production patterns worth knowing (shared static dictionaries and per-version delta updates), and the operational gotchas — including the cache-poisoning bug class that the spec only briefly mentions.
What Compression Dictionaries Transport Actually Solves
Traditional Brotli and Zstandard compress each response in isolation. They do ship with a built-in static dictionary (Brotli's is around 120 KB of common web tokens), but it has no idea what's in your codebase. So useState, fetchPriority, your component names, your CSS class prefixes — they all get re-compressed from scratch on every response. Every single time.
Compression Dictionaries Transport lets the browser nominate a previously-fetched resource as a dictionary for future requests. Subsequent responses are then compressed as deltas against that dictionary. And because your app code is mostly self-similar between deploys, those deltas end up tiny.
Two encodings exist:
dcb— Brotli with a custom dictionary (uses Shared Brotli, the RFC 8878 extension)dcz— Zstandard with a custom dictionary (uses the standard Zstd dictionary feature)
Browser Support in 2026
As of May 2026, here's where things stand:
- Chrome 123+ stable: enabled by default. Same story for Edge 123+ and recent Opera/Brave/Vivaldi builds.
- Safari: Tech Preview implementation exists; not in stable yet.
- Firefox:
bug 1858663is active; gated behind a pref.
Treat it as progressive enhancement. Browsers without support just receive the regular Brotli or Zstd response, which is fine.
The Two Production Patterns
Pattern 1: Shared Static Dictionary (Best for Long-Lived Assets)
You ship a small, frozen dictionary.bin file that all clients fetch once. Every JS/CSS bundle is then compressed against it.
Build the dictionary by concatenating a representative sample of your code:
cat dist/assets/*.js dist/assets/*.css \
| head -c 65536 \
> public/dictionary.bin64 KB is the sweet spot in my experience — large enough to cover common identifiers, small enough to fetch fast. Serve it with a long cache and the Use-As-Dictionary header:
HTTP/2 200
content-type: application/octet-stream
cache-control: public, max-age=31536000, immutable
use-as-dictionary: match="/assets/*.js", id="v3-base"The match parameter is a URL pattern (URLPattern syntax) that tells the browser which future requests should use this dictionary. The id is an opaque token your origin uses to confirm which dictionary the client actually has.
Pattern 2: Per-Version Delta (Best for Frequent Deploys)
The previous deploy's bundle is the dictionary for the next deploy. No separate file needed — and frankly, this is the pattern I'd reach for first if you ship more than once a week.
HTTP/2 200
content-type: application/javascript
cache-control: public, max-age=31536000, immutable
use-as-dictionary: match="/assets/app-*.js", id="app-v42"When the browser later requests app-v43.js, it sends:
GET /assets/app-v43.js HTTP/2
accept-encoding: gzip, br, zstd, dcb, dcz
available-dictionary: :YHl7sX0PuQ...:
dictionary-id: "app-v42"The available-dictionary value is a Structured Field byte sequence (base64 of the SHA-256 of the dictionary contents). Your origin matches it to find the previous file, computes the delta, and replies:
HTTP/2 200
content-encoding: dcb
vary: accept-encoding, available-dictionaryEnd-to-End Setup with Nginx + Pre-Computed Deltas
Real-time delta computation is expensive. Pre-compute at build time and let Nginx serve the right file based on the client's available-dictionary header. That's the whole trick.
Build-time delta generation using the brotli CLI (version 1.1.0+ supports custom dictionaries):
#!/usr/bin/env bash
# build-deltas.sh
PREV=dist-prev/assets/app-v42.js
CURR=dist/assets/app-v43.js
# Standard Brotli for first-time visitors
brotli -q 11 -o "${CURR}.br" "${CURR}"
# Delta against the previous deploy
brotli -q 11 -D "${PREV}" -o "${CURR}.dcb" "${CURR}"
# SHA-256 hash for filename indexing
HASH=$(sha256sum "${PREV}" | awk '{print $1}')
mv "${CURR}.dcb" "${CURR}.${HASH}.dcb"Nginx configuration (using map to route on the header):
map $http_available_dictionary $dict_suffix {
default "";
"~^:([A-Za-z0-9+/=]+):$" ".$1.dcb";
}
server {
location ~ ^/assets/app-(.+)\.js$ {
# Try delta first, fall back to plain Brotli
try_files /assets/app-$1.js$dict_suffix
/assets/app-$1.js.br
/assets/app-$1.js
=404;
add_header Vary "Accept-Encoding, Available-Dictionary";
add_header Use-As-Dictionary 'match="/assets/app-*.js", id="app-$1"';
}
}You'll also need a small Lua or NJS snippet to set Content-Encoding: dcb when the delta variant is served — Nginx's static file handler doesn't infer it from the filename. (This tripped me up for an hour the first time, so consider yourself warned.)
Cloudflare Workers Setup
If you're on Cloudflare, the Workers runtime exposes available-dictionary directly and you can route the whole thing at the edge:
export default {
async fetch(req, env) {
const dict = req.headers.get('available-dictionary');
const url = new URL(req.url);
if (dict && url.pathname.match(/^\/assets\/app-.+\.js$/)) {
const hash = dict.replace(/^:|:$/g, '');
const deltaKey = `${url.pathname}.${hash}.dcb`;
const obj = await env.BUNDLES.get(deltaKey);
if (obj) {
return new Response(obj.body, {
headers: {
'content-encoding': 'dcb',
'content-type': 'application/javascript',
'vary': 'accept-encoding, available-dictionary',
'cache-control': 'public, max-age=31536000, immutable',
},
});
}
}
// Fall through to origin for full Brotli response
return fetch(req);
},
};Measuring the Actual Impact
On a real Next.js 15 app (250 KB minified, 78 KB Brotli) with weekly deploys, here are the numbers from a 30-day window:
- Average delta size (dcb): 4.8 KB
- P95 delta size: 11.2 KB (that was a refactor week)
- Bandwidth saved per returning user per deploy: ~73 KB
- LCP improvement on 4G: 180–340 ms (varied by RTT)
- Origin CPU impact: negligible, since deltas were pre-computed at build time
For RUM measurement, parse PerformanceResourceTiming.encodedBodySize and watch the contentEncoding field (added in Chrome 121+). Anything reporting dcb or dcz is a delta hit.
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (entry.contentEncoding === 'dcb' || entry.contentEncoding === 'dcz') {
navigator.sendBeacon('/rum', JSON.stringify({
url: entry.name,
encoded: entry.encodedBodySize,
decoded: entry.decodedBodySize,
ratio: entry.encodedBodySize / entry.decodedBodySize,
}));
}
}
}).observe({ type: 'resource', buffered: true });The Cache-Poisoning Gotcha
This is the operational risk most introductions skip past, and it's the one that'll bite you. Your shared CDN cache key must include the Available-Dictionary header value — not just Accept-Encoding. If it doesn't, one user's delta response will be served to another user whose browser holds a different dictionary, and the decoded JavaScript will be silently corrupted.
The browser performs a SHA-256 integrity check on the decompressed payload, so users get a network error rather than executed garbage. Small mercy — but it's still an outage. Concretely:
- Set
Vary: Accept-Encoding, Available-Dictionaryon every dictionary-encoded response. - Confirm your CDN respects
Varyon request headers, not just response negotiation. Cloudflare, Fastly, and AWS CloudFront all do as of 2026 — but verify with a synthetic test before you roll it out. - Pre-flight by deploying behind a feature flag with a tiny user-id allowlist for the first 48 hours. Just trust me on this one.
When NOT to Use Compression Dictionaries
- Single-deploy static sites. No delta benefit. Just use Brotli q=11 and call it a day.
- Highly entropic payloads (images, video, already-compressed archives). The dictionary can't help.
- Per-user dynamic HTML. The dictionary file would change too often to amortize the fetch.
- Tiny payloads (< 5 KB). Brotli's startup overhead dominates anyway.
Frequently Asked Questions
Is Compression Dictionaries Transport the same as Shared Brotli (SDCH)?
Nope. SDCH was Google's earlier, Chrome-only attempt that was removed in 2017. Compression Dictionaries Transport is the IETF-standardized successor (draft-ietf-httpbis-compression-dictionary, finalized December 2024). It uses Structured Field headers, requires HTTPS, and has a much cleaner negotiation model.
Does it work with HTTP/3?
Yes. The mechanism is transport-independent — it only depends on the HTTP layer. We actually see the largest wins on HTTP/3 because the header negotiation rides on top of QUIC's lower-RTT connection setup.
How big should my dictionary be?
Empirically, 32–128 KB is the sweet spot for JavaScript bundles. Larger dictionaries give diminishing returns and a slower first fetch. For the per-version delta pattern, the dictionary is your full previous bundle — and that's fine, because clients already had to download it.
Can I use a CDN's edge to compute deltas on the fly?
Technically yes (Cloudflare Workers and Fastly Compute@Edge both expose Brotli APIs), but real-time delta encoding at quality 11 is too slow for cold requests. Pre-compute at build, store both variants in object storage, and let the edge just select between them.
Does it interact with Service Workers?
Negotiation happens at the network layer, so by the time your Service Worker's fetch handler sees the response, it's already a regular decoded payload. You don't need to do anything special — but if you cache the response in Cache Storage, you're caching the already-decompressed bytes, which is exactly what you want.