Text Compression: Serve HTML with Brotli or gzip
Text files compress extremely well. HTML, CSS, JavaScript, JSON and SVG are full of repeated words and markup, so Brotli or gzip typically shrinks them by 70–90%. The browser decompresses them almost instantly, so the only effect visitors notice is that pages arrive sooner, especially on mobile networks.
Why it matters
Every byte of HTML has to arrive before the browser can finish parsing the page and discover the images, styles and scripts it needs. An uncompressed 100 KB HTML document on a slow mobile connection can easily add half a second before anything useful happens. Compression is one of the cheapest performance wins there is: usually one setting, no code changes.
Browsers announce what they can decode in the Accept-Encoding request header (all modern browsers
accept br and gzip), and the server says what it used in the Content-Encoding response header.
What we check
We request the page the way a browser does, asking for gzip, deflate, br, and read the
Content-Encoding of the HTML response.
| Result | When |
|---|---|
| Passed | the HTML is compressed with Brotli, gzip, zstd or deflate |
| Failed | the HTML is not compressed |
| Info | the page is under 1 KB, where compression makes no difference |
This check covers the HTML document. The Lighthouse opportunities in your report flag uncompressed CSS and JavaScript files separately.
You can check by hand with:
curl -sI -H 'Accept-Encoding: br, gzip' https://example.com/ | grep -i content-encoding
How to fix
CDN
Cloudflare, Fastly, CloudFront, Vercel and Netlify compress text responses by default. If yours
doesn’t, look for a “compression” or “Brotli” setting. Make sure your origin doesn’t send
Cache-Control: no-transform, which tells proxies not to compress.
Nginx
gzip on;
gzip_comp_level 5;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;
text/html is always compressed once gzip on is set. For Brotli, install the ngx_brotli
module and add brotli on; with the same types.
Apache
<IfModule mod_deflate.c>
AddOutputFilterByType DEFLATE text/html text/css application/javascript application/json image/svg+xml
</IfModule>
Apache 2.4.26 and later can also serve Brotli with mod_brotli.
Node.js and other app servers
Compression is usually better left to the reverse proxy or CDN in front of your app. If the app serves traffic directly, use the framework’s compression middleware.
Don’t compress twice
Images (JPEG, PNG, WebP, AVIF), video and fonts in WOFF2 format are already compressed. Running gzip over them wastes CPU and saves nothing, so leave them out of the compressed types.
Further reading: MDN: Compression in HTTP.