README
http-compression
)
Optimal compression (http-compression
warns against serving resources uncompressed
or using an inappropriate encoding.
Why is this important?
One of the fastest and easiest ways one can improve web site/app performance is to reduce the amount of data sent to the client by using HTTP compression. This not only reduces the data used by the user, but can also significantly cut down on the server costs.
Here are a few rules to follow to get the most out of compressing resources:
Only compress resources for which the result of the compression will be smaller than original size.
In general text-based resources (HTML, CSS, JavaScript, SVGs, etc.) compress very well especially if the file is not very small. The same goes for some other file formats (e.g.: ICO files, web fonts such as EOT, OTF, and TTF, etc.)
However, compressing resources that are already compressed (e.g.: images, audio files, PDFs, etc.) not only wastes CPU resources, but usually results in little to no reduction, or in some cases, results in an increase in file size.
The same applies to resources that are very small because of the overhead of compression file formats.
Use the most efficient compression method.
gzip is the most used encoding method currently as it strikes a good balance between compression ratio (as high as 70% especially for larger files) and encoding time and is supported pretty much everywhere.
Better savings can be achieved using Zopfli which can reduce the size on average 3–8% more than gzip. Since Zopfli output (for the gzip option) is valid gzip content, Zopfli works everywhere gzip works. The only down side is that encoding takes more time than gzip, making Zopfli more suitable for static content (i.e. encoding resources as part of a build script, not on the fly).
Things can be improved even further using Brotli. This encoding can achieve 20–26% higher compression ratios over Zopfli. However, this encoding is not compatible with gzip, limiting the support to modern browsers and its usage to only over HTTPS (as proxies misinterpret unknown encodings).
As a rule, for best performance and compatibility, resources should be served compressed with Zopfli over insecure HTTP, and Brotli when sending over HTTPS with a fallback to Zopfli if HTTPS is not supported.
Avoid using deprecated or not widely supported compression formats, and
Content-Type
values.Avoid using deprecated
Content-Type
values such asx-gzip
. Some user agents may alias them to the correct, current equivalent value (e.g.: aliasx-gzip
to gzip), but that is not always true.Also avoid using encodings that are not widely supported (e.g.:
compress
,bzip2
,sdch
, etc.), and/or may not be as efficient, or can create problems (e.g.:deflate
).Avoid potential caching related issues.
When resources are served compressed, they should be served with the
Vary
header containing theAccept-Encoding
value (or with something such asCache-Control: private
that prevents caching in proxy caches and such altogether).This needs to be done to avoid problems such as an intermediate proxy caching the compressed version of the resource and then sending it to all user agents, whether they support that encoding or even requested the compressed version.
Resources should be served compressed only when requested as such, appropriately encoded, and without relying on user agent sniffing.
The
Accept-Encoding
request header specified should be respected. Sending a resource encoded with a different encoding than one of the ones accepted can lead to problems.Here are some examples:
If the user agent makes a request containing the
Accept-Encoding: identity
header, that means it wants the response to not be transformed in any way, so the server should send the data uncompress.If the user agent makes a request containing the
Accept-Encoding: gzip, br
header, that means it wants the response to either be uncompress or compress with one of the specified encodings, namely: gzip (or the gzip compatible Zopfli) or Brotli. In the optimal case, the server sends the data compress with Zopfli over HTTP, and Brotli over HTTPS.
Dealing with special cases.
One such special case is
SVGZ
files that areSVG
files compressed with gzip. Since they are already compressed, they shouldn't be compressed again. However, sending them without theContent-Encoding: gzip
header will create problems as user agents will not know they need to decompress before trying to display them.
What does the hint check?
The hint checks for the use cases previously specified. Namely, it checks that:
Only resources for which the result of the compression is smaller than original size are served compressed.
The most efficient encodings are used (by default the hint check if Zopfli is used over HTTP and Brotli over
HTTPS
, however that can be changed, see:Can the hint be configured?
section).Deprecated or not widely supported encodings, and
Content-Type
values are not used.Potential caching related issues are avoided.
Resources are served compressed only when requested as such, are appropriately encoded, and no user-agent detection is done.
Special cases (such as
SVGZ
) are handled correctly.
Examples that trigger the hint
Resource that should be compressed is not served compressed.
e.g.: When the request for https://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate, br
response is
HTTP/... 200 OK
...
Content-Type: text/javascript
<file content>
Resource that should not be compressed is served compressed.
e.g.: When the request for https://example.com/example.png
contains
...
Accept-Encoding: gzip, deflate, br
response is
HTTP/... 200 OK
...
Content-Encoding: br
Content-Type: image/png
Vary: Accept-Encoding
<file content compressed with Brotli>
Resource that compressed results in a bigger or equal size to the uncompressed size is still served compressed.
e.g.: For http://example.com/example.js
containing only const x = 5;
,
using the defaults, the sizes may be as follows.
original size: 13 bytes
gzip size: 38 bytes
zopfli size: 33 bytes
brotli size: 17 bytes
When the request for http://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate
response is
HTTP/... 200 OK
...
Content-Encoding: gzip
Content-Type: text/javascript
Vary: Accept-Encoding
<file content compressed with gzip>
Resource that should be compressed is served compressed with deprecated
or disallowed compression method or Content-Encoding
value.
e.g.: When the request for http://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate
response contains deprecated x-gzip
value for Content-Encoding
HTTP/... 200 OK
...
Content-Encoding: x-gzip
Content-Type: text/javascript
Vary: Accept-Encoding
<file content compressed with gzip>
response is compressed with disallowed compress
compression method
HTTP/... 200 OK
...
Content-Encoding: compress
Content-Type: text/javascript
Vary: Accept-Encoding
<file content compressed with compress>
or response tries to use deprecated SDCH
HTTP/... 200 OK
...
Content-Encoding: gzip,
Content-Type: text/javascript
Get-Dictionary: /dictionaries/search_dict, /dictionaries/help_dict
Vary: Accept-Encoding
<file content compressed with gzip>
Resource that should be compressed is not served compressed using Zopfli over HTTP.
e.g.: When the request for http://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate
response is
HTTP/... 200 OK
...
Content-Encoding: gzip
Content-Type: text/javascript
Vary: Accept-Encoding
<content compressed with gzip>
Resource that should be compressed is served compressed using Brotli over HTTP.
e.g.: When the request for http://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate, br
response is
HTTP/... 200 OK
...
Content-Encoding: br
Content-Type: text/javascript
Vary: Accept-Encoding
<content compressed with Brotli>
Resource that should be compressed is not served compressed using Brotli over HTTPS.
e.g.: When the request for https://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate, br
response is
HTTP/... 200 OK
...
Content-Encoding: gzip
Content-Type: text/javascript
Vary: Accept-Encoding
<content compressed with Zopfli>
Resource that is served compressed doesn't account for caching
(e.g.: is not served with the Vary
header with the Accept-Encoding
value included, or something such as Cache-Control: private
).
e.g.: When the request for https://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate, br
response is
HTTP/... 200 OK
...
Content-Encoding: br
Content-Type: text/javascript
<content compressed with Brotli>
Resource is blindly served compressed using gzip no matter what the user agent advertises as supporting.
E.g.: When the request for https://example.com/example.js
contains
...
Accept-Encoding: br
response is
HTTP/... 200 OK
...
Content-Encoding: gzip
Content-Type: text/javascript
Vary: Accept-Encoding
<content compressed with gzip>
Resource is served compressed only for certain user agents.
E.g.: When the request for https://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate, br
User-Agent: Mozilla/5.0 Gecko
response is
HTTP/... 200 OK
...
Content-Type: text/javascript
<file content>
however, when requested with
...
Accept-Encoding: gzip, deflate, br
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:57.0) Gecko/20100101 Firefox/57.0
response is
HTTP/... 200 OK
...
Content-Encoding: br
Content-Type: text/javascript
Vary: Accept-Encoding
<content compressed with Brotli>
SVGZ
resource is not served with Content-Encoding: gzip
header:
E.g.: When the request for https://example.com/example.svgz
contains
...
Accept-Encoding: gzip, deflate, br
response is
HTTP/... 200 OK
...
Content-Type: image/svg+xml
<file content>
Examples that pass the hint
Resource that should be compressed is served compressed using Zopfli
over HTTP and with the Vary: Accept-Encoding
header.
e.g.: When the request for http://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate
response is
HTTP/... 200 OK
...
Content-Encoding: gzip
Content-Type: text/javascript
Vary: Accept-Encoding
<content compressed with Zopfli>
Resource that should be compressed is served compressed using Brotli
over HTTPS and with the Vary: Accept-Encoding
header.
e.g.: When the request for https://example.com/example.js
contains
...
Accept-Encoding: gzip, deflate, br
response is
HTTP/... 200 OK
...
Content-Encoding: br
Content-Type: text/javascript
Vary: Accept-Encoding
<content compressed with Brotli>
Resource that should not be compressed is not served compressed.
e.g.: When the request for https://example.com/example.png
contains
...
Accept-Encoding: gzip, deflate, br
response is
HTTP/... 200 OK
...
Content-Type: image/png
<image content>
SVGZ
resource is served with Content-Encoding: gzip
header:
e.g.: When the request for https://example.com/example.svgz
contains
...
Accept-Encoding: gzip, deflate, br
response is
HTTP/... 200 OK
...
Content-Encoding: gzip
Content-Type: image/svg+xml
<SVGZ content>
How to configure the server to pass this hint
How to configure Apache
Apache can be configured to conditionally (based on media type)
compress resources using gzip as well as send the appropriate
Content-Encoding
and Vary
headers using mod_deflate
and the AddOutputFilterByType
directive.
For Zopfli, there isn't a core Apache module or directive to do it, However, since compressing things using Zopfli takes more time, it's usually indicated to do it as part of your build step. Once that is done, Apache needs to be configure to server those pre-compressed files when gzip compression is requested by the user agent.
Starting with Apache v2.4.26
, mod_brotli
and the
AddOutputFilterByType
directive can be used
to conditionally compress with Brotli as well as add the
Content-Encoding
and Vary
headers. However, like Zopfli, Brotli can
take more time. So, when provided, mod_brotli
may be used to compress
dynamic resources (especially if set to use lower compression quality
levels), but for static resources it's indicated to compress them as
part of the build process and configure Apache to serve those
pre-compressed resources whenever Brotli compression is requested over
HTTPS.
If you don't want to start from scratch, below is a generic starter snippet that contains the necessary configurations to ensure that commonly used file types are served compressed and with the appropriate headers, and thus, make your web site/app pass this hint.
Important notes:
The following relies on Apache being configure to have the correct filename extensions to media types mappings (see Apache section from
content-type
hint).For Zopfli and Brotli this snippet assumes that running the build step will result in 3 version for every resource:
- the original (e.g.: script.js) - you should also have this file in case the user agent doesn't requests things compressed
- the file compressed with Zopfli (e.g.: script.js.gz)
- the file compressed with Brotli (e.g.: script.js.br)
<IfModule mod_headers.c>
<IfModule mod_rewrite.c>
# Turn on the rewrite engine (this is necessary in order for
# the `RewriteRule` directives to work).
#
# https://httpd.apache.org/docs/current/mod/core.html#options
RewriteEngine On
# Enable the `FollowSymLinks` option if it isn't already.
#
# https://httpd.apache.org/docs/current/mod/core.html#options
Options +FollowSymlinks
# If the web host doesn't allow the `FollowSymlinks` option,
# it needs to be comment out or removed, and then the following
# uncomment, but be aware of the performance impact.
#
# https://httpd.apache.org/docs/current/misc/perf-tuning.html#symlinks
# Options +SymLinksIfOwnerMatch
# Depending on how the server is set up, you may also need to
# use the `RewriteOptions` directive to enable some options for
# the rewrite engine.
#
# https://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriteoptions
# RewriteBase /
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# 1) Brotli
# If `Accept-Encoding` header contains `br`
RewriteCond "%{HTTP:Accept-encoding}" "br"
# and the request is made over HTTPS.
RewriteCond "%{HTTPS}" "on"
# The Brotli pre-compressed version of the file exists
# (e.g.: `script.js` is requested and `script.js.gz` exists).
RewriteCond "%{REQUEST_FILENAME}\.br" "-s"
# Then, serve the Brotli pre-compressed version of the file.
RewriteRule "^(.*)" "$1\.br" [QSA]
# Set the correct media type of the requested file. Otherwise,
# it will be served with the br media type since the file has
# the `.br` extension.
#
# Also, set the special purpose environment variables so
# that Apache doesn't recompress these files.
RewriteRule "\.(ico|cur)\.br