Shared dictionaries

Shared dictionaries (RFC 9842 ) let your origin compress a response against a copy of the same or a different resource that the visitor's browser already has cached. Only the difference between the two resources travels over the wire.

This is most effective for versioned assets that change incrementally between deploys, such as JavaScript bundles, CSS files, and framework chunks. After a deploy, returning visitors can receive the new asset as a small delta against the version they already have, instead of redownloading the full file.

Cloudflare supports shared dictionaries in passthrough mode: your origin manages dictionaries and produces delta-compressed responses. Cloudflare forwards the dictionary headers and dcb/dcz content encodings without modifying or recompressing them, and varies the cache so each delta-compressed variant is stored separately.

For background on the other compression algorithms Cloudflare supports, refer to Content compression.

Shared dictionaries work when all of the following are true:

• The visitor's browser supports compression dictionary transport . Today, this is Chrome 130 or later, Edge 130 or later, or another Chromium browser at the same version.
• The browser request includes dcb or dcz in Accept-Encoding and an Available-Dictionary header.
• Your origin returns a delta-compressed response with Content-Encoding: dcb or dcz and a Vary header that includes Accept-Encoding, Available-Dictionary.
• The dictionary, the delta response, and the request are served over HTTPS from the same origin. Per RFC 9842, Section 8 , compression dictionary transport is HTTPS-only.

The protocol uses two new request and response headers and two new content encodings:

The first response for a versioned asset includes Use-As-Dictionary, and the browser stores the response. On subsequent requests for assets matching the pattern, the browser sends Available-Dictionary: :<sha256>: and adds dcb, dcz to Accept-Encoding. Your origin compresses the new asset against the dictionary and returns it with Content-Encoding: dcb or dcz. The browser uses its stored copy to reconstruct the full response.

The match value in Use-As-Dictionary is a WHATWG URL Pattern , not a regular expression. Match patterns operate on the percent-encoded URL path and are scoped to the same origin as the dictionary.

The Available-Dictionary value is a Structured Field byte sequence: the base64-encoded SHA-256 hash wrapped in colons (for example, :pZGm1Av0IEBKARczz7exkNYsZb8LzaMrV7J32a2fFG4=:). The colons are part of the syntax.

Enabling shared dictionaries is a two-part task:

1. Turn on passthrough for your zone in Cloudflare. This tells Cloudflare to forward dictionary headers and vary cache entries correctly.
2. Update your origin server to mark assets as dictionaries and return delta-compressed responses against them.

The work of creating dictionaries and compressing new responses against them happens at your origin, not at Cloudflare.

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/settings/shared_dictionary_mode" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"value": "passthrough"
	}'

For each versioned asset you want to use as a dictionary, include a Use-As-Dictionary header on the first response:

Use-As-Dictionary: match="/static/app-*.js", type="raw"
Cache-Control: public, max-age=31536000, immutable
Content-Encoding: br

The match value tells the browser which future request URLs should advertise this dictionary. It is a WHATWG URL Pattern, does not support regular expressions, and must resolve to the same origin as the dictionary.

When a request arrives with an Available-Dictionary header, look up the dictionary by its SHA-256 hash. If you have it, compress the response against it and return:

Content-Encoding: dcz
Vary: Accept-Encoding, Available-Dictionary
Cache-Control: public, max-age=31536000, immutable

RFC 9842, Section 6.2 requires the Vary: Accept-Encoding, Available-Dictionary response header so that browser caches do not serve the wrong variant. Cloudflare's cache also varies on these headers when passthrough is on.

When the browser does not advertise Available-Dictionary, the hash does not match a dictionary you have, or the browser does not advertise dcb/dcz, return the response with normal Brotli, Zstandard, or Gzip compression.

Cloudflare does not prescribe a specific origin implementation. Common starting points include:

• A reverse proxy. Configure NGINX, Caddy, or a similar proxy to attach Use-As-Dictionary headers and produce delta responses with a sidecar process.
• Native support in your application server. Extend your existing compression middleware to read Available-Dictionary and emit dcb or dcz.

To confirm a request is using a shared dictionary, request the asset twice. The second request advertises the dictionary you received in the first response.

# Prime the dictionary.
curl -sI -H "Accept-Encoding: br, gzip, zstd, dcb, dcz" \
  https://example.com/static/app.v1.js

# Request the next version, advertising the dictionary you just received.
# Replace <hash> with the base64-encoded SHA-256 of the first response.
# The surrounding colons are part of the Structured Field syntax
# and are required by RFC 9842, Section 2.2.
curl -sI -H "Accept-Encoding: br, gzip, zstd, dcb, dcz" \
  -H "Available-Dictionary: :<hash>:" \
  https://example.com/static/app.v2.js

The second response should include Content-Encoding: dcz (or dcb), Vary: Accept-Encoding, Available-Dictionary, and a Content-Length significantly smaller than a non-delta response.

You can also use canicompress.com to confirm your browser supports shared dictionaries and to inspect a working delta-compressed response.

• Origin-side work is required. In passthrough mode, Cloudflare does not generate dictionaries or compute deltas. If your origin does not produce dcb/dcz responses, no compression savings occur.
• Body-modifying features are incompatible. Cloudflare features that rewrite response bodies do not work on delta-compressed responses. Turn these features off on dictionary-compressed paths, or set cache-control: no-transform on the origin response. For details, refer to Content compression.
• Browser support is partial. Visitors on browsers that do not request dcb or dcz continue to receive Brotli, Zstandard, or Gzip per your existing Compression Rules and default compression behavior.
• Same-origin only. Per RFC 9842, Section 9.3.1 , dictionaries are scoped to the response origin. Cross-origin dictionary use is not supported.