9.4 Brotli and Modern Compression

Intermediate

What you will learn

1. What Brotli is and why it wins (on the wire and in the CPU profile).

2. The deployment reality: ngx_brotli — dynamic module, Module 15's build path, and the lesson's verified-instead configuration.

3. The dual-stack pattern: brotli + gzip side by side, negotiation doing the routing.

4. Static Brotli ( brotli_static) — the pre-compressed endgame for versioned assets.

5. The decision table: when brotli pays, when gzip remains enough.

1. The case for Brotli

Brotli (Google, 2013–2015, shipped in every modern browser) is a DEFLATE successor with a bigger, smarter toolbox:

For a text-heavy site, brotli is a straight upgrade for ~95% of traffic — with gzip remaining as the universal fallback. The wire cost is one header of negotiation:

GET /app.js
Accept-Encoding: gzip, deflate, br        ← client ranks its codecs

HTTP/1.1 200 OK
Content-Encoding: br                      ← server picked the best offer
Vary: Accept-Encoding

2. The deployment reality

Stated plainly: ngx_brotli is a third-party module — the official nginx.org packages don't ship it, so brotli on; fails at nginx -t here exactly as it does on most stock installs. The path to running it is Module 15's dynamic-module curriculum: build ngx_brotli as an .so against your exact binary ( --with-compat matters), load_module, done. The scaffolding you get today is the config that lights up the moment the module loads: the dual-stack locations and the negotiation routing, ready to reuse.

The configuration you'll run once it does — presented here as the canonical shape (this is the config Module 15's build will light up):

# after Module 15: load_module modules/ngx_http_brotli_filter_module.so;
#                   load_module modules/ngx_http_brotli_static_module.so;

brotli            on;
brotli_comp_level 6;          # ~4-6 is the knee; br-6 ≈ gzip-9 size, gzip-6 CPU
brotli_types      text/plain text/css text/javascript application/json
                  application/javascript application/xml image/svg+xml;
brotli_static    on;          # serve .br files from disk when present

gzip             on;          # the fallback stack stays armed
gzip_comp_level  6;
gzip_types       (same list);
gzip_vary        on;

The directive vocabulary is deliberately gzip-mirrored ( brotli_types, brotli_min_length, brotli_static, brotli_comp_level) — everything you know transfers one-to-one, which is the mark of a well-designed module.

3. The dual-stack pattern

With both codecs armed, NGINX's filter chain negotiates per request — the pattern to internalize (with gzip standing in for brotli until Module 15's build):

client sends Accept-Encoding: br            → Brotli response (Content-Encoding: br)
client sends Accept-Encoding: gzip          → gzip response
client sends gzip, br (ranked)              → brotli wins (preferred codec)
client sends none (ancient/probe)           → identity, Vary noted

Two production notes on the stack:

• Order is the preference, and yours is fixed: with brotli on, NGINX prefers br over gzip when the client offers both — the correct default (smaller wire), and the reason you can deploy brotli with zero risk to gzip-only clients: negotiation routes them, Vary keeps caches honest, nobody gets bytes they can't decode.

• CPU symmetry: both codecs in the chain means one runs per response, not both (filters short-circuit on the chosen encoding). Your CPU budget stays single-codec; the dual stack is a routing decision, not a doubling.

4. Static Brotli, concretely

The deploy pipeline shape (works identically for gzip_static, shown brotli-side since it shines there):

# build step (per release):
brotli -q 11 -k -f dist/app.js        # writes dist/app.js.br
gzip  -9  -k -f dist/app.js           # writes dist/app.js.gz  (fallback)

# NGINX:
brotli_static on;    # request /app.js with AE:br  -> serve app.js.br from disk
gzip_static  on;     # request /app.js with AE:gzip-> serve app.js.gz from disk

Rules that make statics safe: there is no mtime guard — the static module serves whatever .br is on disk; freshness is the pipeline's contract (deploy source and artifact atomically); the extension is stripped for the client ( /app.js is the URL, .br never appears); and versioned filenames (the Module 8 key-versioning habit) make the whole invalidation question moot.

5. The decision table

Try it yourself

The gzip side of every experiment in this lesson runs today — the brotli side lights up after Module 15:

1. Model the negotiation. With curl --compressed (offers gzip, deflate, br, zstd — check curl -V), observe which Content-Encoding your server picks today; then send explicit subsets: -H 'Accept-Encoding: br' (identity — no br support yet), -H 'Accept-Encoding: gzip' (gzip). You've just walked the dual-stack routing table with gzip as the stand-in.

2. The ratio baseline. Record gzip's ratio on your fixtures — after Module 15's build, the same fixtures through br will show the 15–25% delta on the exact same numbers. A before/after experiment you own end-to-end.

3. Static pre-compression rehearsal. gzip -9 -k a fixture in /var/www/, add gzip_static on; to a location, and fetch it — zero-CPU compressed serving, today. The brotli version is the same line with br.

Q&A

Q1. Client sends Accept-Encoding: gzip, br. What's served, and why is that safe for a gzip-only client?

Q2. Why are Brotli levels 10–11 absent from the runtime knee but perfect for build pipelines?

Q3. Your edge can't load third-party modules. What's the honest compression ceiling?

Q4. A stale .br file sits next to a fresh source file. What does brotli_static do?

Takeaways

• Brotli: 15–25% smaller than gzip on text at comparable CPU, built-in web dictionary, 16 MB window — preferred whenever the client offers it.

• It's a third-party module ( ngx_brotli): Module 15's dynamic-module build is the on-ramp; the config shape (this lesson) is ready for it.

• Deploy as a dual stack — negotiation routes, Vary protects, gzip remains the universal fallback; CPU stays single-codec.

• brotli_static + build-time q11 is the pre-compression endgame; mirrors gzip_static line-for-line.

• When you can't have it: gzip discipline is the honest 90% — and you now hold both playbooks.