Optimize your Hugo Blog With Unlighthouse

November 18, 2026 update: The original walkthrough below is from 2023. I’ve added the current Partytown + GA4 setup, including a silent tracking failure, the fix, and fresh performance measurements.

Recently Google let me see the new Analytics dashboard (they moved from… Something something analytics to something something Analytics 4). And one of they things I saw was that my blog’s performance was bad!

“I have failed you”

In general the blog’s infrastructure didn’t get much love since I opened it a few years ago, so a cleanup for performance and content is probably in order.

Get initial Lighthouse results

What’s Lighthouse? It’s a tool that Google provides to measure the performance of your site. It’s available as a Chrome extension, but also as a CLI tool that you can run on your site. So I thought that the first order of business was to run Lighthouse on my site and see what I’m getting both for Mobile and Desktop.

But wait

Then, thanks to a Fireship video, I found out about Unlighthouse, which seems even better for this use case! Unlighthouse runs Lighthouse reports for all pages of your site, and then generates a report with the results.

So let’s run it! From the getting started guide, looks like we need to use Node.js 16. To make this “clean”, add a .nvmrc file to a new folder in your Hugo site called performance.

nvm use 16
npx unlighthouse --site https://mrnice.dev/

The report is so cool:

Unlighthouse report

Analyzing the results

This is a lot of information. Let’s start looking at it.

UX is more important than the machine

Looking at the homepage itself as it loads, there are too many words. I’ll slim it down - even if the site loads fast, if the homepage is confusing, people will bounce out. So let’s slim it down.

Before

Homepage - before

After

Homepage - after

Much better. Let’s go the analytics themselves now.

Wait, which device and I looking at?

I know that most people are using my site from Desktop AND Mobile.

“Analytics 1”

We need to look at both. Looking at the report, looks like it’s from “emulated mobile”, so we need to re-run it for Desktop. A quick look at the documentation for the configuration and the “selecting device” section shows that we’ll need to set up a configuration file for each option. Since I know that eventually I’ll want to automate this, it’s a good chance to write a shell script to work with this. I went a little overboard as I tern to, and used gum to build a fun CLI tool for this, which I’m dubbing lighthouse-plus.sh.

#!/bin/zsh

# Check that gum is installed
if ! command -v gum &> /dev/null
then
    echo "gum could not be found, run 'brew install gum'"
    exit
fi

# Check that currently using node 16
if [[ $(node --version) != *"v16"* ]]; then
  echo "Please use node 16"
  exit
fi

# Get device name ('desktop' or 'mobile') from command line argument, if not
# provided, use `gum choose` to choose interactively
if [[ -z $1 ]]; then
  device=$(gum choose "desktop" "mobile")
else
  device=$1
fi

npx unlighthouse --config-file "$device"-unlighthouse.config.ts

Now we can run lighthouse-plus.sh and get the results for both Desktop and Mobile. Let’s iterate on Desktop and the Home page first: Many fixes will be relevant to all pages, and it’s the most important page and device. Also, it’s what I use right now for development so iterations will be faster for me 🤸‍♀️.

Improving performance

Reduce unused JavaScript

The first thing that jumps out is that I have two unused JavaScript files:

“results 1”

The first one, https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js, is from “How to Add Math Expressions to Hugo Blog - the Shortest Guide Possible”, which I honestly forgot about. I don’t have any math expressions in my blog’s homepage, so why am I loading it here? Let’s look at the old post…

Choose where to include JS scripts

To display math we’re going to use a JS script. We’ll include the JS in our layouts/_default/baseof.html file, to make sure that we have Math support in every single page.

Oh. That’s why. I put it there.

“Performance meme”

To fix that, I tried using page parameters, and only include the script on pages that need it. To debug the templates and figure out which .html file I want to edit (instead of baseof.html), I used a cool trick: I added a {{ printf "%#v" . }} to the top of the file, and then looked at the output of the page. This gave me a bit of useless info:

& hugolib.pageState {
    pageOutputs: [] * hugolib.pageOutput {
        ( * hugolib.pageOutput)(0x14000c4cc80), ( * hugolib.pageOutput)(0x14000c4d040)
    },
    pageOutputTemplateVariationsState: ( * atomic.Uint32)(0x14000238180),
    pageOutput: ( * hugolib.pageOutput)(0x14000c4cc80),
    pageCommon: ( * hugolib.pageCommon)(0x14001177200)
}

I went through a bunch of the html templates in the layouts folder, until I found the right one (for my template, it’s themes/hermit-fork/layouts/posts/single.html, but of course for your site it’s going to probably be different). Then, when I replaced the previous printf with {{ printf "%#v" .Params }}, I saw exactly what I needed:

maps.Params {
    "date": time.Date(2021, time.June, 12, 12, 15, 16, 0, time.Local),
    "draft": false,
    "images": [] string {
        "/images/math-teacher.png"
    },
    "iscjklanguage": false,
    "lastmod": time.Date(2021, time.June, 12, 12, 15, 16, 0, time.Local),
    "publishdate": time.Date(2021, time.June, 12, 12, 15, 16, 0, time.Local),
    "render_math": true,
    "tags": [] string {
        "howto", "hugo", "meta", "math"
    },
    "title": "How to Add Math Expressions to Hugo Blog - the Shortest Guide Possible",
    "toc": false
}

See the render_math there? It’s because I added this parameter to the post’s front matter:

---
title: "How to Add Math Expressions to Hugo Blog - the Shortest Guide Possible"
date: 2021-06-12T12:15:16+03:00
draft: false
toc: false
images:
  - "/images/math-teacher.png" 
tags: 
  - howto
  - hugo
  - meta
  - math
render_math: true
---

I could even live-debug my if statement with {{ if .Params.render_math }} which returned true! The final working solution was to add this to the template:

+       <!-- MathJax start -->
+       {{ if .Params.render_math -}}
+               <script type="text/javascript" id="MathJax-script" async
+                       src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
+               </script>
+               <script type="text/x-mathjax-config">
+                       MathJax.Hub.Config({
+                       tex2jax: {
+                               inlineMath: [['\\(','\\)']],
+                               displayMath: [['$$','$$'], ['\[','\]']],
+                               processEscapes: true,
+                               processEnvironments: true,
+                               skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
+                               TeX: { equationNumbers: { autoNumber: "AMS" },
+                                       extensions: ["AMSmath.js", "AMSsymbols.js"] }
+                       }
+                       });
+               </script>
+               <script type="text/x-mathjax-config">
+                       MathJax.Hub.Queue(function() {
+                               // Fix <code> tags after MathJax finishes running. This is a
+                               // hack to overcome a shortcoming of Markdown. Discussion at
+                               // https://github.com/mojombo/jekyll/issues/199
+                               var all = MathJax.Hub.getAllJax(), i;
+                               for(i = 0; i < all.length; i += 1) {
+                                       all[i].SourceElement().parentNode.className += ' has-jax';
+                               }
+                       });
+               </script>
+       {{- end -}}
+       <!-- MathJax end -->

Before:

math-before

And after:

math-after

Removing JS from the critical path with Partytown 🎉

Now the GA-4 GTM script is slowing down the page even more! Damn it!

Damn it

I don’t want to remove it, but I also don’t want it to slow down the page. So I opted to install Partytown, simply following this guide.

There were a few things that didn’t work 1-to-1 from the guide:

  1. I had to replace the internal analytics partial with a custom one that uses type="text/partytown" instead of normal text/javascript. So I copied the original partial from Hugo’s files on GitHub.
  2. Since I deploy to GitHub Pages, I had to cause Jekyll to add the ~partytown directory. Since Jekyll doesn’t include directories that start with certain special characters when building and deploying the site.
  3. I used nvm and an .nvmrc file to make sure I’m using the correct Node.js version.

To fix 2, I added the following _config.yml file to the root of my site (the public directory):

include:
  - "~partytown"
November 2026 update: keep the worker, fix the analytics

Plot twist: a fast analytics script that doesn’t send analytics isn’t much of a win.

Google Search Console was still sending me search-performance reports, but GA4 said “Data collection isn’t active.” Those are independent: Search Console reports how the site performs in Google Search; it doesn’t prove the browser’s Analytics tag is working.

My GA measurement ID was correct. The tag downloaded successfully. There were even commands in dataLayer. None of that proved collection was happening.

The bug was in my old Partytown runtime, version 0.8.0. Google’s current tag read document.scripts during initialization. Partytown’s emulated document didn’t implement that property, so this operation failed:

[].slice.call(document.scripts);
// TypeError: Cannot convert undefined or null to object

Google caught the exception internally, leaving the tag uninitialized without an obvious uncaught error in the page’s console. Pausing on caught exceptions in the Partytown worker exposed it. I don’t know exactly when collection stopped; finding the current failure doesn’t establish the historical cutoff.

Running the same tag on the main thread, using a browser-only override, sent a real page_view that Google accepted with HTTP 204. Useful diagnostic! Not the fix I wanted: keeping that work off the main thread was the whole point.

Upgrade the runtime, not the measurement ID

The fix was to replace the old package with the supported @qwik.dev/partytown release, pinned to 1.0.5:

npm uninstall @builder.io/partytown
npm install --save-dev --save-exact @qwik.dev/partytown@1.0.5

That release implements document.scripts. I also updated package.hugo.json to use the same package and exact version. My current project uses Node 24 and Hugo 0.168, rather than the Node 16 setup in the original walkthrough above.

Here’s the relevant Hugo configuration. Merge it with the existing sections rather than adding a second [params] table:

[params]
partytownLib = "/~partytown/1.0.5/"

[module]
[[module.mounts]]
source = "assets"
target = "assets"
[[module.mounts]]
source = "node_modules/@qwik.dev/partytown/lib/partytown.js"
target = "assets/js/partytown.js"
[[module.mounts]]
source = "static"
target = "static"
[[module.mounts]]
source = "node_modules/@qwik.dev/partytown/lib"
target = "static/~partytown/1.0.5"
files = ["*.js", "*.html"]

Two details matter:

  • Publish the HTML too. The newer release includes partytown-sandbox-sw.html; my old JS-only filter was no longer sufficient. Hugo 0.168 calls the mount filter files, not the removed includeFiles.
  • Version the library directory. The bootstrap and runtime must agree. Giving the new runtime its own service-worker scope avoids mixing a cached old worker with the new code on returning visits. Keep the package pin, mount destination, and partytownLib value in sync.

In the theme’s baseof.html, the configuration before the existing Partytown bootstrap is now:

<script>
  partytown = {
    lib: {{ .Site.Params.partytownLib | default "/~partytown/" | relURL }},
    forward: ['dataLayer.push']
  };
</script>

Both GA scripts still use type="text/partytown": the external tag loader and the inline dataLayer/gtag('js', ...)/gtag('config', ...) initialization. The custom analytics partial still respects Hugo’s configured privacy-disable and Do Not Track controls. No extra native GA loader, no main-thread exception for the Google tag, and no fake document.scripts = [] shim.

Verify collection, not just loading

I checked the repaired production build in a real browser:

  • One page_view per page load, with the expected measurement ID, sent to Google’s /g/collect endpoint and accepted with HTTP 204.
  • The requests came from the dedicated worker, not a main-thread fallback.
  • Cold and warm homepage visits, an article, and a returning browser with the old service worker already installed.
  • A native 390×844/DPR3 mobile viewport and Do Not Track suppressing measurement.
  • Main-thread dataLayer.push forwarding a data-layer object into the worker.

A successful download or a full queue is not a substitute for that check. HTTP 204 verifies transport, not appearance in your private GA reports: check GA Realtime as well.

Partytown isn’t magic, either. Its default fallback can execute scripts on the main thread if worker startup fails. Its GA4 integration documentation also notes that exit-time user_engagement isn’t reliable from a worker. This upgrade fixes the observed initialization failure, not every analytics trade-off.

Did keeping Partytown preserve performance?

I reran Lighthouse on production builds, with three cold runs each for mobile and desktop, interleaving the old and repaired versions. Same Lighthouse 13.5.0, Chrome 155.0.8059.84, default simulated throttling, local static servers, and no request blocking. These are homepage lab results, not a new whole-site Unlighthouse run or field measurements.

Homepage Mobile score Mobile LCP Mobile TBT Desktop score Desktop LCP Desktop TBT
Old Partytown 0.8.0, broken tracking 99 1.805 s 43 ms 100 0.405 s 0 ms
Partytown 1.0.5, working worker tracking 98 2.006 s 64 ms 100 0.407 s 0 ms

Each cell is its metric’s median; all 12 audits completed without warnings. This is not zero-cost analytics: against the broken tracker, mobile median LCP increased by about 201 ms and TBT by 21 ms. But the tag is working again without abandoning the worker-based approach.

Lesson learned: verify the analytics and the performance. A great Lighthouse score won’t tell you that your tracker quietly stopped tracking.

Improving CLS (Cumulative Layout Shift)

This one was simple: Just slapped height and width on the homepage logo. I found out that I’m loading that image from a 3rd party site instead of from my static files, so updated that as well.

Improving accessibility

I only got 74?! That sucks, I really want the site to be accessible. There were a bunch of issues here:

  1. No alt text on the site logo. Added descriptive text
  2. “Background and foreground colors do not have a sufficient contrast ratio”. In the Hermit theme, in _predefined.scss, there’s a @mixin called dimmed, which lowers the opacity by 40%. While it looks cool, the contrast IS hard to read. So I changed it to 90% instead of 60%, and now it’s much more legible, even if it’s not as cool.

Improving SEO

“Document does not have a meta description”

After Googling for a bit, this seems like a known issue that hasn’t been fixed yet, see Pull Request. I just copy pasted the fix from the Pull Request (including the CR comment) by adding the description to the structured-data.html partial and the description to my config.toml file.

In config.toml:

[params]
  description = "..."

In themes/hermit-fork/layouts/partials/structured-data.html:

<meta
  name="description"
  content="{{ with .Description }}{{ . }}{{ else }}{{if .IsPage}}{{ .Summary }}{{ else }}{{ with .Site.Params.description }}{{ . }}{{ end }}{{ end }}{{ end -}}"
/>

“Structured data is valid”

I didn’t know about this one! Appears that Google has something called “Structured data” which is a standardized format for providing information about a page and classifying the page content. Seems like we want two features here:

  1. Add the site logo as the Structured Data logo using this guide
  2. For each blog post, add the “BlogPosting” structured data using this guide

I started with 1 for the homepage, by adding this into the structured-data.html partial:

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Organization",
    "url": {{ .Site.BaseURL }},
    "logo": {{ (print .Site.BaseURL .Site.Params.siteLogoRelPath) }}
  }
</script>

And this to the config.toml:

[params]
  siteLogoRelPath = "images/site-logo.png"

Then, run your site locally, inspect the <head> until you find the JSON-LD tag, copy it, and paste it into the JSON-LD Playground to test that it worked out correctly.

Re-run and compare

I WIN!

win

Other random cleanups

Get rid of the “tweet” Hugo shortcode warning

Every time I ran the server I saw these warnings: The "tweet" shortcode will soon require two named parameters: user and id.. I decided to fix it instead of continuing to ignore the warnings (I’m not a monster). It’s a simple change:

-{ { < tweet 1388749844240535553 > } }
+{ { < tweet user="ShayNehmad" id="1388749844240535553" > } }

Summary

I learned a TON about Hugo, Jekyll, GitHub, and the Web in general. I am also DONE, with only two side-projects left for later: Automate this with CI, and add structured data to the blog posts. Another day!

Photo generated by DALL-E with the prompt “An expressive oil painting of a lighthouse watching over a sea made from paper”.