DEV Community

Cover image for Add Microsoft Clarity to Hugo with Cloudflare Zaraz - Without Redeploying
Roxroy
Roxroy

Posted on

Add Microsoft Clarity to Hugo with Cloudflare Zaraz - Without Redeploying

#hugo #analytics #cloudflare #webdev

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:

  1. Microsoft Clarity may not appear as a native tool in the Zaraz catalog, so it must be added using Custom HTML.
  2. Zaraz does not automatically bypass your website's Content Security Policy. A restrictive CSP may still need to allow Clarity's domains.

Here is the complete setup.

What the architecture looks like

Instead of embedding Clarity in Hugo:

Hugo template
    |
    +-- Microsoft Clarity script
Enter fullscreen mode Exit fullscreen mode

The script is managed through Cloudflare instead:

Visitor
    |
    v
Cloudflare Zaraz
    |
    +-- Loads Microsoft Clarity
    |
    v
Hugo site on Cloudflare Pages
Enter fullscreen mode Exit fullscreen mode

The Hugo site remains responsible for the site itself. Zaraz becomes the control layer for the analytics script.

Prerequisites

You need:

  • A Hugo site on Cloudflare Pages
  • A custom domain associated with the Pages project
  • Access to Cloudflare Zaraz
  • A Microsoft Clarity project
  • The tracking code generated for that project

Cloudflare requires a custom domain before Zaraz can be enabled for a Pages project.

Step 1: Get the Microsoft Clarity tracking code

Open your project in Microsoft Clarity and go to:

Settings → Setup
Enter fullscreen mode Exit fullscreen mode

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.

Step 2: Enable Zaraz

In Cloudflare:

  1. Select the zone containing the Pages custom domain.
  2. Open Web Tag Management.
  3. Open Zaraz.
  4. Go to Tag Setup.

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 loader to Hugo.

Step 3: Add Clarity as Custom HTML

Clarity may not appear in the available third-party tool catalog. In that case:

  1. Select Add new tool.
  2. Choose Custom HTML.
  3. Name the tool Microsoft Clarity.
  4. Save the tool.
  5. Create a custom action named Load Clarity.
  6. Paste the full Clarity tracking code into the Custom HTML field.
  7. Assign the built-in Pageview trigger.
  8. Save and publish the configuration.

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 loading a new document.

Step 4: Configure consent

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:

  • Which visitors require consent
  • Whether Clarity may set or access cookies
  • Whether the tool fires before consent
  • Whether consent withdrawal prevents future tracking
  • Whether the privacy policy describes session recording and heatmaps

Step 5: Configure Clarity masking

Clarity records user interactions, so masking deserves more attention than it would for basic pageview analytics.

Microsoft Clarity provides three masking modes:

  • Strict: masks all page content
  • Balanced: masks content Clarity classifies as sensitive
  • Relaxed: leaves most page content visible, while input fields and dropdowns remain masked

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.

Step 6: Test the Content Security Policy

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:

  1. Open the production site in a private browser window.
  2. Disable ad blockers for the test.
  3. Open the browser developer tools.
  4. Check the Console for CSP violations.
  5. Check the Network panel for requests containing clarity.
  6. Interact with several pages.

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
Enter fullscreen mode Exit fullscreen mode

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.

Step 7: Verify Clarity collection

Microsoft documents two primary ways to verify an installation:

  • Look for real-time activity in the Clarity project.
  • Inspect the browser network traffic for POST requests to Clarity's collection endpoint.

A successful test should confirm:

  • The Clarity script loads once
  • Collection requests are sent
  • No CSP errors appear
  • The visit reaches the correct Clarity project
  • Navigation between Hugo pages produces expected sessions
  • Sensitive information is masked
  • Consent rules work as intended

Avoid duplicate installations

Before publishing the Zaraz configuration, search for an existing Clarity installation in:

  • Hugo base templates
  • Analytics partials
  • Hugo configuration files
  • Google Tag Manager
  • Cloudflare Snippets or Workers
  • Other tag-management tools

Do not load Clarity through both Hugo and Zaraz. Duplicate initialization can create unreliable recordings and unnecessary requests.

Disable Clarity without deploying

Once the implementation is verified, Clarity can be disabled from:

Cloudflare
→ Zaraz
→ Tag Setup
→ Tools Configuration
→ Third-party tools
Enter fullscreen mode Exit fullscreen mode

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.

What this approach solves

This setup provides:

  • A no-redeploy Clarity kill switch
  • Separation between site code and analytics configuration
  • Central management through Cloudflare
  • A reusable process across multiple static sites
  • Faster rollback when a tracking tool causes problems

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.

Final checklist

Before considering the work complete:

  • [ ] Pages uses a custom domain
  • [ ] Zaraz auto-injection is enabled
  • [ ] Clarity is configured as Custom HTML
  • [ ] The Pageview trigger is assigned
  • [ ] The tool is assigned to the correct consent purpose
  • [ ] Clarity masking is reviewed
  • [ ] CSP behavior is tested
  • [ ] No duplicate installation exists
  • [ ] Network collection requests succeed
  • [ ] Clarity can be disabled through Zaraz

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.

Top comments (0)