Adding Microsoft Clarity to a Hugo site normally means placing its tracking script in a base template, rebuilding the site, and deploying the change.
That works, but it couples analytics configuration to your release process.
For a static site hosted on Cloudflare Pages, Cloudflare Zaraz provides another option: manage the Clarity script through Cloudflare instead of storing it in the Hugo repository.
Once configured, Clarity can be enabled or disabled without another Hugo build or Cloudflare Pages deployment.
There are two important caveats:
Here is the complete setup.
Instead of embedding Clarity in Hugo:
Hugo template
|
+-- Microsoft Clarity script
The script is managed through Cloudflare instead:
Visitor
|
v
Cloudflare Zaraz
|
+-- Loads Microsoft Clarity
|
v
Hugo site on Cloudflare Pages
The Hugo site remains responsible for the site itself. Zaraz becomes the control layer for the analytics script.
You need:
Cloudflare requires a custom domain before Zaraz can be enabled for a Pages project.
Open your project in Microsoft Clarity and go to:
Settings → Setup
Choose the manual installation method and copy the complete tracking code.
Each Clarity website project has its own tracking code. Microsoft normally instructs you to paste this code into the website's <head>
, but in this setup Zaraz will load it instead. Do not manually recreate the script - use the exact version generated for your Clarity project.
In Cloudflare:
Confirm that Zaraz is enabled for the correct production hostname.
Under Zaraz settings, also confirm that Auto-inject script is enabled. Cloudflare enables this setting by default. It injects the Zaraz runtime automatically, which means you do not need to add a Zaraz to Hugo.
Clarity may not appear in the available third-party tool catalog. In that case:
Microsoft Clarity
.Load Clarity
.Zaraz actions run when their assigned triggers fire. The built-in Pageview trigger is intended for actions that should run when a page is loaded.
For a conventional Hugo site, leave Single Page Application support disabled. Hugo normally serves a new HTML document for each page. SPA support is only needed when client-side navigation changes the URL without a new document.
Do not skip this step when using Zaraz Consent Management.
Create or select an analytics purpose, then assign the Microsoft Clarity Custom HTML tool to that purpose.
Cloudflare warns that a newly added tool is not assigned to a consent purpose automatically. An unassigned tool skips consent by default and may run before the visitor makes a consent choice.
The correct implementation depends on the jurisdictions you serve and your privacy requirements, but the technical configuration should not silently bypass your consent model.
At minimum, verify:
Clarity records user interactions, so masking deserves more attention than it would for basic pageview analytics.
Microsoft Clarity provides three masking modes:
Balanced is the default. Clarity also supports masking or unmasking specific elements through CSS selectors.
For a public Hugo marketing site, Balanced may be an acceptable starting point after reviewing actual recordings.
For authenticated, financial, healthcare, administrative, or customer-account pages, use stricter controls. Do not assume the default masking rules cover every sensitive element.
This is the most likely technical problem.
Moving the script into Zaraz means you no longer need to store the Clarity snippet in Hugo. It does not mean the browser ignores the site's CSP.
Clarity still needs to load Microsoft resources and send collection requests. Microsoft states that websites with a CSP must allow Clarity's required domains, or browsers may block the integration. Its guidance identifies Clarity's domains and c.bing.com
as relevant sources.
Before changing the CSP:
clarity
.Do not weaken the policy with broad wildcards unless there is a justified requirement.
Add only the required sources to the relevant directives, which may include:
script-src
connect-src
img-src
default-src
Where the CSP is generated through Hugo or a Cloudflare Pages _headers
file, this correction will require one source change and a single deployment.
After that initial CSP correction, routine Clarity enablement can still be controlled entirely through Zaraz.
Microsoft documents two primary ways to verify an installation:
A successful test should confirm:
Before publishing the Zaraz configuration, search for an existing Clarity installation in:
Do not load Clarity through both Hugo and Zaraz. Duplicate initialization can create unreliable recordings and unnecessary requests.
Once the implementation is verified, Clarity can be disabled from:
Cloudflare
→ Zaraz
→ Tag Setup
→ Tools Configuration
→ Third-party tools
Locate the Microsoft Clarity tool and turn off its Enabled toggle.
Cloudflare also lets you disable an individual action while leaving the tool configured. After publishing the change, reload the website and confirm that Clarity requests have stopped.
No Hugo source change, build, or Pages deployment is required.
This setup provides:
It also introduces a new responsibility: Zaraz configuration now exists outside Git.
Document the setup, restrict Cloudflare permissions, and use Preview and Publish mode when changes should be reviewed before going live. Cloudflare supports both immediate publishing and a preview workflow.
Before considering the work complete:
Cloudflare Zaraz does not eliminate every analytics concern. You still need to manage consent, masking, CSP rules, and configuration governance.
What it does eliminate is the need to redeploy a Hugo site every time Microsoft Clarity needs to be switched on or off.