{"slug": "add-microsoft-clarity-to-hugo-with-cloudflare-zaraz-without-redeploying", "title": "Add Microsoft Clarity to Hugo with Cloudflare Zaraz - Without Redeploying", "summary": "A developer explains how to add Microsoft Clarity to a Hugo site using Cloudflare Zaraz, eliminating the need to rebuild and redeploy the site for analytics changes. The setup moves the Clarity script from the Hugo repository to Cloudflare's control layer, enabling toggling without a new build. Key caveats include proper consent configuration, content security policy adjustments, and masking settings for sensitive pages.", "body_md": "Adding Microsoft Clarity to a Hugo site normally means placing its tracking script in a base template, rebuilding the site, and deploying the change.\n\nThat works, but it couples analytics configuration to your release process.\n\nFor 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.\n\nOnce configured, Clarity can be enabled or disabled without another Hugo build or Cloudflare Pages deployment.\n\nThere are two important caveats:\n\nHere is the complete setup.\n\nInstead of embedding Clarity in Hugo:\n\n```\nHugo template\n |\n +-- Microsoft Clarity script\n```\n\nThe script is managed through Cloudflare instead:\n\n```\nVisitor\n |\n v\nCloudflare Zaraz\n |\n +-- Loads Microsoft Clarity\n |\n v\nHugo site on Cloudflare Pages\n```\n\nThe Hugo site remains responsible for the site itself. Zaraz becomes the control layer for the analytics script.\n\nYou need:\n\nCloudflare requires a custom domain before Zaraz can be enabled for a Pages project.\n\nOpen your project in Microsoft Clarity and go to:\n\n```\nSettings → Setup\n```\n\nChoose the manual installation method and copy the complete tracking code.\n\nEach Clarity website project has its own tracking code. Microsoft normally instructs you to paste this code into the website's ``\n\n, but in this setup Zaraz will load it instead. Do not manually recreate the script - use the exact version generated for your Clarity project.\n\nIn Cloudflare:\n\nConfirm that Zaraz is enabled for the correct production hostname.\n\nUnder 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.\n\nClarity may not appear in the available third-party tool catalog. In that case:\n\n`Microsoft Clarity`\n\n.`Load Clarity`\n\n.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.\n\nFor 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.\n\nDo not skip this step when using Zaraz Consent Management.\n\nCreate or select an analytics purpose, then assign the Microsoft Clarity Custom HTML tool to that purpose.\n\nCloudflare 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.\n\nThe correct implementation depends on the jurisdictions you serve and your privacy requirements, but the technical configuration should not silently bypass your consent model.\n\nAt minimum, verify:\n\nClarity records user interactions, so masking deserves more attention than it would for basic pageview analytics.\n\nMicrosoft Clarity provides three masking modes:\n\nBalanced is the default. Clarity also supports masking or unmasking specific elements through CSS selectors.\n\nFor a public Hugo marketing site, Balanced may be an acceptable starting point after reviewing actual recordings.\n\nFor authenticated, financial, healthcare, administrative, or customer-account pages, use stricter controls. Do not assume the default masking rules cover every sensitive element.\n\nThis is the most likely technical problem.\n\nMoving 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.\n\nClarity 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`\n\nas relevant sources.\n\nBefore changing the CSP:\n\n`clarity`\n\n.Do not weaken the policy with broad wildcards unless there is a justified requirement.\n\nAdd only the required sources to the relevant directives, which may include:\n\n```\nscript-src\nconnect-src\nimg-src\ndefault-src\n```\n\nWhere the CSP is generated through Hugo or a Cloudflare Pages `_headers`\n\nfile, this correction will require one source change and a single deployment.\n\nAfter that initial CSP correction, routine Clarity enablement can still be controlled entirely through Zaraz.\n\nMicrosoft documents two primary ways to verify an installation:\n\nA successful test should confirm:\n\nBefore publishing the Zaraz configuration, search for an existing Clarity installation in:\n\nDo not load Clarity through both Hugo and Zaraz. Duplicate initialization can create unreliable recordings and unnecessary requests.\n\nOnce the implementation is verified, Clarity can be disabled from:\n\n```\nCloudflare\n→ Zaraz\n→ Tag Setup\n→ Tools Configuration\n→ Third-party tools\n```\n\nLocate the Microsoft Clarity tool and turn off its **Enabled** toggle.\n\nCloudflare 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.\n\nNo Hugo source change, build, or Pages deployment is required.\n\nThis setup provides:\n\nIt also introduces a new responsibility: Zaraz configuration now exists outside Git.\n\nDocument 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.\n\nBefore considering the work complete:\n\nCloudflare Zaraz does not eliminate every analytics concern. You still need to manage consent, masking, CSP rules, and configuration governance.\n\nWhat it does eliminate is the need to redeploy a Hugo site every time Microsoft Clarity needs to be switched on or off.", "url": "https://wpnews.pro/news/add-microsoft-clarity-to-hugo-with-cloudflare-zaraz-without-redeploying", "canonical_source": "https://dev.to/roxroy/add-microsoft-clarity-to-hugo-with-cloudflare-zaraz-without-redeploying-2khg", "published_at": "2026-07-22 04:00:00+00:00", "updated_at": "2026-07-22 04:04:12.262152+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["Microsoft Clarity", "Hugo", "Cloudflare Zaraz", "Cloudflare Pages"], "alternates": {"html": "https://wpnews.pro/news/add-microsoft-clarity-to-hugo-with-cloudflare-zaraz-without-redeploying", "markdown": "https://wpnews.pro/news/add-microsoft-clarity-to-hugo-with-cloudflare-zaraz-without-redeploying.md", "text": "https://wpnews.pro/news/add-microsoft-clarity-to-hugo-with-cloudflare-zaraz-without-redeploying.txt", "jsonld": "https://wpnews.pro/news/add-microsoft-clarity-to-hugo-with-cloudflare-zaraz-without-redeploying.jsonld"}}