Hugo cache busting - Generate static assets hash filenames

What is cache busting?

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

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

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

There are some disadvantages with caching,

Whenever you updated the static resources, cached resources are not loaded into webbrowsers. The reason is cache assets are stored in CDN with expiry time.

To avoid this, Cache busting is introduced.

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

  • Adding version to static assets

For example, Style assets is styles.css file declared in 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 version, So that caching providers assume that files are updated and reloaded into cache.

  • Adding hash to filenames

The same can be replaced styles.css with styles-hash.css

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

Hugo cache busting

hugo provides fingerprint module to generates hashing It uses 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 an security for an file to avoid modification to render in a browser. Permalink is an variable to returns full path of an resource.

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 contains key and value pairs for conversion sass to css This will compile and generate 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 generates unique file names for static assets for every updates to this.


In this tutorial, you learn how to generates unique hashing file names for static resources. This is used to enable cache busting for hugo css/sass styles javascript and image files.

Join 6,000 subscribers and get a daily digest of full stack tutorials delivered to your inbox directly.No spam ever. Unsubscribe any time.

Similar Posts
You'll get a notification every time a post gets published here.