git clone https://github.com/google/brotli.git
cd brotli

rm -rf out
mkdir out && cd out

cmake .. -DCMAKE_BUILD_TYPE=Release -DBROTLI_BUILD_TOOLS=ON

make brotli

cd ..

cd research

bazel build dictionary_generator

your-project/
├── brotli/ # The cloned brotli repository
└── js/
    ├── jquery-3.7.1.js
    └── jquery-4.0.0-beta.js

Important Note for macOS users

Encountering dyld errors (like "Library not loaded"):

If you haven't already, export DYLD_LIBRARY_PATH in your current shell session before running the brotli commands:

export DYLD_LIBRARY_PATH=brotli/out/

This tells the dynamic linker where to find the Brotli libraries. This path assumes you are in your-project/ and brotli/out/ is the correct relative path to the libraries.

Create the Shared Brotli Dictionary using jquery-3.7.1.js as the source material.

brotli/research/bazel-bin/dictionary_generator -o js/jquery.dict js/jquery-3.7.1.js

This creates js/jquery.dict.

Compress jQuery 4.0.0-beta WITH the Dictionary:

brotli/out/brotli --dictionary=js/jquery.dict js/jquery-4.0.0-beta.js -o js/jquery-4.0.0-beta.js.br -q 11 -f

This creates js/jquery-4.0.0-beta.js.br.

We will also compress jQuery 4.0.0-beta without the Dictionary to get a baseline for comparison:

brotli/out/brotli js/jquery-4.0.0-beta.js -o js/jquery-4.0.0-beta.js.no-dict.br -q 11 -f

This creates js/jquery-4.0.0-beta.js.no-dict.br.

Netlify #

To configure Netlify to use compression dictionaries, we need to set up the appropriate headers in the _headers file placed at the root of the site.

# Link the jQuery 4.0.0-beta.js file to the dictionary
/js/jquery-4.0.0-beta.js
  Link: ; rel="dictionary"
  Content-Type: application/javascript; charset=utf-8

# The dictionary file is cached for a long time
/js/jquery.dict
  Cache-Control: public, max-age=31536000, immutable

# No dictionary compression for jquery 4.0.0-beta.js
/js/jquery-4.0.0-beta.js.no-dict.br
  Content-Encoding: br
  Content-Type: application/javascript; charset=utf-8

This configuration does the following:

1. Specifies jquery-4.0.0-beta.js as a dictionary using the Link header to the dictionary file (jquery.dict)
2. Provides headers for the dictionary file, ensuring it is cached for a long time
3. Specifies the Content-Encoding for the compressed file without the dictionary, allowing the browser to decompress it correctly

The HTML and JavaScript that run the tests #

Rather than show the full HTML code, I chose to focus on the JavaScript that fetches the file sizes and checks if jQuery is loaded correctly. The HTML is minimal and is available on Github.

The JavaScript code below fetches the sizes of the jQuery files and displays them in the HTML. It also checks if jQuery is loaded correctly and provides a button to test its functionality.

fetchAndDisplaySize is an asynchronous function that fetches a file from the server, retrieves its size, and displays it in the specified HTML element. It handles errors gracefully and updates the UI accordingly.

async function fetchAndDisplaySize(url, elementId) {
	const element = document.getElementById(elementId);
	try {
		const response = await fetch(url, { cache: 'no-store' });
		if (!response.ok) {
			throw new Error(`HTTP error! status: ${response.status} for ${url}`);
		}
		const blob = await response.blob();
		element.textContent = blob.size.toLocaleString() + ' B';
	} catch (error) {
		console.error('Error fetching size for', url, error);
		element.textContent = 'Error';
		element.classList.add('text-red-500');
	}
}

We add an event listener to the DOMContentLoaded event to ensure the DOM is fully loaded before running our JavaScript code. This function calls fetchAndDisplaySize for each jQuery file we want to check, passing the URL and the ID of the HTML element where the size will be displayed.

document.addEventListener('DOMContentLoaded', () => {
	fetchAndDisplaySize('/js/jquery-3.7.1.js', 'size-jq371');
	fetchAndDisplaySize('/js/jquery-4.0.0-beta.js', 'size-jq4beta');
	fetchAndDisplaySize('/js/jquery-4.0.0-beta.js.no-dict.br', 'size-jq4beta-br-nodict');
	fetchAndDisplaySize('/js/jquery-4.0.0-beta.js.br', 'size-jq4beta-br-dict');

	// jQuery test
	const statusElement = document.getElementById('jquery-status');
	const statusDot = statusElement.querySelector('.status-dot');

	if (typeof jQuery !== 'undefined') {
		statusDot.classList.add('loaded');
		statusElement.childNodes[ 1 ].nodeValue = ' jQuery successfully loaded!';
		$('#testButton').on('click', function () {
			$('#testResult').text('jQuery is working! Button clicked at ' + new Date().toLocaleTimeString());
		});
	} else {
		statusDot.classList.add('error');
		statusElement.childNodes[ 1 ].nodeValue = ' jQuery failed to load.';
		console.error('jQuery is not loaded!');
		document.getElementById('testButton').disabled = true;
		document.getElementById('testButton').classList.add('opacity-50', 'cursor-not-allowed');
	}
});

Browser Support #

As of the date of writing, compression dictionaries are only supported in Chrome 127 and later (and I would assume other Chromium-based browsers). Firefox and Safari do not yet support compression dictionaries.

I expect this to change in the future as WebKit (Safari) and Firefox implement support for compression dictionaries but, until it does, be careful when deploying this beyond testing.

Working Example #

You can see a working example of this setup on the demo site: https://compression-dictionary-demo.netlify.app/.

In Chrome the difference between the compressed file with the dictionary and the one without is significant. Other browsers may not work at all or may not show the same results.

Links and resources #

• Compression dictionaries
  • Compression Dictionary Transport
  • Getting Real Small with Compression Dictionaries
  • Shared Dictionary Compression
  • Use as dictionary