Serving Pre-compressed Brotli Files with NGINX’s brotli_static Module

by ,

We have by far the largest RPM repository with NGINX module packages and VMODs for Varnish. If you want to install NGINX, Varnish, and lots of useful performance/security software with smooth yum upgrades for production use, this is the repository for you.
Active subscription is required.

Introduction to the Brotli compression

Web performance is a crucial for any online business or service. One of the ways to improve web performance is with the compression algorithms like Gzip and Brotli. They help reduce the size of files sent over the network and save bandwidth in the process.

NGINX is an extremely efficient and configurable web server, and includes Gzip compression, by default. It can be extended with support of superior Brotli compression algorithm. Here we will focus on generating pre-compressed Brotli files and serving them efficiently with NGINX using the brotli_static directive.


  • A working NGINX installation
  • Basic understanding of NGINX configuration

Installation of brotli command-line utility

To create pre-compressed Brotli files, you need to have brotli utility installed. This can be easily done on any modern bistro like so:

yum install brotli

Installation of brotli_static module

If your NGINX installation does not include the brotli_static module, you need to install it first.

Following that, you can enable the brotli_static module, by editing /etc/nginx/nginx.conf and placing the following at the top:

load_module modules/ngx_http_brotli_static_module.so;

Make sure to reload NGINX configuration afterwards, for running NGINX instance to pick up on the new module:

systemctl reload nginx

Generating Pre-compressed Brotli Files

First, you’ll need to generate Brotli compressed versions of your static files. Using the brotli CLI tool, you can do this as follows:

brotli --best /path/to/your/file.js

This will create a file.js.br compressed version in the same directory.

NGINX Configuration

To serve these precompressed files, add the following directives in your NGINX configuration file:

http { ... server { ... location /static/ { ... brotli_static on; ... } } }

With brotli_static on;, NGINX will look for .br files and serve them if they are available. The main benefit of this approach is reduced CPU impact. It is a superior approach to dynamically compressing files upon requests, because the only time you will compress your website static files, is during deployment, for example. Other times, CPU usage is dramatically reduced, because NGINX can now serve pre-compressed files directly.

Another performance benefit lies in the use of --best flag, which will ensure maximum compression of level 11. This compression level is not acceptable for dynamic compression on-the-fly due to being too slow. But if you rely on pre-compression, you can opt to the best compression which creates smallest files.

So one real-life example, is if you manage WordPress updates yourself or you can integrate running the following command prior to upgrading WordPress:

# Loop through and compress each .css and .js file
find "/path/to/wordpress/wp-content" \( -iname '*.css' -o -iname '*.js' \) -exec bash -c 'brotli --best "$0"' {} \;

This will create pre-compressed Brotli files for each CSS and Javascript under wp-content. The following NGINX configuration will then allow serving them compressed without any CPU impact:

http { ... server { ... location /wp-content/ { ... brotli_static on; ... } } }


After you’ve made these changes, don’t forget to test your NGINX configuration.
First, you need to reload it to apply the changes:

nginx -t && systemctl reload nginx

You can then use tools like curl to confirm that Brotli pre-compressed files are served:

curl -I -H 'Accept-Encoding: br' https://example.com/file.js

As long as you see the response includes Content-Encoding: br, it means that NGINX properly handles Brotli compression.


It is important to understand that brotli on; directive applies to dynamic compression on-the-fly (which belongs to filter NGINX module of Brotli). So if you are relying on pre-compressed files, you may want to omit that and use brotli_static on; instead, in your NGINX configuration.


Serving precompressed Brotli files can significantly improve your web server’s performance by reducing the amount of data sent over the network. It also frees up CPU resources as you offload the compression step to the time of file creation rather than on-the-fly during the request. Implementing this on an NGINX server is straightforward, especially with the brotli_static module. Happy optimizing!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

This site uses Akismet to reduce spam. Learn how your comment data is processed.