Hugo cache-busting - Generate static assets hash filenames

Hugo cache-busting - Generate static assets hash filenames

What is cache busting?

Cache busting is a technique to load the assets from url instead of from the browser cache.

Caching is very useful to improve the performance of static assets like CSS javascript and image type files. These can be configured at the server to store these assets for a longer time and these will be expired within the time specified.

Websites used CDN to load static assets faster the reason is Static files are cached in CDN like Cloudflare.

There are some disadvantages to caching,

Whenever you update the static resources, cached resources are not loaded into web browsers.

The reason is cache assets are stored in CDN with an expiry time.

To avoid this, Cache busting is introduced.

There are many ways we can avoid Cache busting using the below approaches

  • Adding version to static assets

For example, Style assets is a styles.css file declared in an HTML file as follows

<link rel="stylesheet" href="/assets/styles.css" crossorigin="anonymous" />

Adding version tag to style.css as follows

<link rel="stylesheet" href="/assets/styles.css?v=1" crossorigin="anonymous" />

Whenever styles are updated, you can increment the version, So that caching providers assume that files are updated and reloaded into the cache.

  • Adding hash to filenames

The same replaces styles.css with styles-hash.css.

<link
  rel="stylesheet"
  href="/assets/styles.4epmaklEYZOa.css"
  integrity="sha512-4epmaklEYZOa"
  crossorigin="anonymous"
/>

Hugo cache busting

Hugo provides a fingerprint module to generate hashing It uses the default SHA-256 hash

Let’s generate hash-style file names using fingerprint

{{ $css := resources.Get "css/app.css" | resources.Fingerprint "sha512"}}
<link
  rel="stylesheet"
  href="{{ $css.Permalink }}"
  integrity="{{ $css.Data.Integrity }}"
  crossorigin="anonymous"
/>

integrity is a security for a file to avoid modification to render in a browser. Permalink is a variable to return the resource full path.

if you are using sass/scss files, you can use Hugo pipes

Hugo pipes are introduced to compile sass files into CSS files

{{ $options := (dict "targetPath" "main.css" "outputStyle" "compressed"
"includePaths" (slice "node_modules")) -}} {{ $css := resources.Get
"scss/app.scss" | toCSS $options }} {{ $secureCSS := $css |
resources.Fingerprint "sha512" -}}
<link
  rel="stylesheet"
  href="{{ $secureCSS.Permalink }}"
  integrity="{{ $secureCSS.Data.Integrity }}"
  crossorigin="anonymous"
/>

Options contain key and value pairs for conversion sass to CSS It compiles and generates hash CSS filenames.

how we can generate javascript hash filename

{{ $app := resources.Get "js/main.js" -}}
<script src="{{ $app.Permalink }}"></script>

With this, It will generate unique file names for static assets for every update to this.

Conclusion

In this tutorial, learn to generate unique hashing file names for static resources. It enables cache busting for Hugo CSS/sass styles javascript and image files.