From 820c05136063d7926ebfce12241bcabad5261f0a Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 14 May 2026 14:56:40 +1000
Subject: [PATCH] docs(clarity): document env var name and call out common
 mistake

Add an environment variables section to the Clarity docs showing the
correct `NUXT_PUBLIC_SCRIPTS_CLARITY_ID` env var (registry key is
`clarity`, not `microsoftClarity`), matching the convention used by
other registry entries. Closes #769.
---
 docs/content/scripts/clarity.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/content/scripts/clarity.md b/docs/content/scripts/clarity.md
index 8fbc7b23d..3c3dbd85a 100644
--- a/docs/content/scripts/clarity.md
+++ b/docs/content/scripts/clarity.md
@@ -54,3 +54,25 @@ consent.set({
 ```
 
 See [Clarity cookie consent](https://learn.microsoft.com/en-us/clarity/setup-and-installation/cookie-consent) for details.
+
+## With Environment Variables
+
+You can supply your Clarity project id with an environment variable. The env var name follows the registry key (`clarity`), not the marketing name:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      clarity: { trigger: 'onNuxtReady' },
+    },
+  },
+})
+```
+
+```text [.env]
+NUXT_PUBLIC_SCRIPTS_CLARITY_ID=<YOUR_PROJECT_ID>
+```
+
+::warning
+The env var key must match the registry key. For Clarity that is `NUXT_PUBLIC_SCRIPTS_CLARITY_ID`, not `NUXT_PUBLIC_SCRIPTS_MICROSOFT_CLARITY_ID`.
+::