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!

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.

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:

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

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.

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:

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.htmlfile, to make sure that we have Math support in every single page.
Oh. That’s why. I put it there.

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:

And after:

Removing JS from the critical path with Partytown 🎉
Now the GA-4 GTM script is slowing down the page even more! 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:
- I had to replace the internal analytics partial with a custom one that uses
type="text/partytown"instead of normaltext/javascript. So I copied the original partial from Hugo’s files on GitHub. - Since I deploy to GitHub Pages, I had to cause Jekyll to add the
~partytowndirectory. Since Jekyll doesn’t include directories that start with certain special characters when building and deploying the site. - I used
nvmand an.nvmrcfile 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 filterfiles, not the removedincludeFiles. - 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
partytownLibvalue 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_viewper page load, with the expected measurement ID, sent to Google’s/g/collectendpoint 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.pushforwarding 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:
- No alt text on the site logo. Added descriptive text
- “Background and foreground colors do not have a sufficient contrast ratio”.
In the Hermit theme, in
_predefined.scss, there’s a@mixincalleddimmed, 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:
- Add the site logo as the Structured Data logo using this guide
- 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!

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”.