feat(plugin-clarity-analytics): supports clarity analytics (#553)

FuckDoctors · web-flow · commit 3ed7477fd48a · 2025-07-31T22:41:04.000+08:00
diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts
@@ -47,6 +47,7 @@ export const sidebarEn: SidebarOptions = {
 
   '/plugins/analytics/': [
     'baidu-analytics',
+    'clarity-analytics',
     'google-analytics',
     'umami-analytics',
   ],
diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts
@@ -47,6 +47,7 @@ export const sidebarZh: SidebarOptions = {
 
   '/zh/plugins/analytics/': [
     'baidu-analytics',
+    'clarity-analytics',
     'google-analytics',
     'umami-analytics',
   ],
diff --git a/docs/plugins/analytics/clarity-analytics.md b/docs/plugins/analytics/clarity-analytics.md
@@ -0,0 +1,54 @@
+---
+icon: chart-no-axes-combined
+---
+
+# clarity-analytics
+
+<NpmBadge package="@vuepress/plugin-clarity-analytics" />
+
+Integrate [Clarity Analytics](https://clarity.microsoft.com/) into VuePress.
+
+## Usage
+
+```bash
+npm i -D @vuepress/plugin-clarity-analytics@next
+```
+
+```ts title=".vuepress/config.ts"
+import { clarityAnalyticsPlugin } from '@vuepress/plugin-clarity-analytics'
+
+export default {
+  plugins: [
+    clarityAnalyticsPlugin({
+      // options
+    }),
+  ],
+}
+```
+
+### Reporting Events
+
+The plugin helps you understand user interaction with your website.
+
+[Supported Features](https://learn.microsoft.com/en-us/clarity/setup-and-installation/about-clarity#supported-features)
+
+- Session recordings
+- Heatmaps
+- Event and funnel tracking
+- Chat and summarize with Copilot
+
+After using this plugin, the global `clarity()` function is available on the `window` object for [advanced features](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-api).
+
+## Options
+
+### id
+
+- Type: `string`
+- Required: Yes
+- Details: Clarity Analytics project ID.
+
+### crossOrigin
+
+- Type: `string`
+- Default: `undefined`
+- Details: The `crossorigin` attribute, provides support for `CORS`.
diff --git a/docs/zh/plugins/analytics/clarity-analytics.md b/docs/zh/plugins/analytics/clarity-analytics.md
@@ -0,0 +1,54 @@
+---
+icon: chart-no-axes-combined
+---
+
+# clarity-analytics
+
+<NpmBadge package="@vuepress/plugin-clarity-analytics" />
+
+将 [Clarity Analytics](https://clarity.microsoft.com/) 集成到 VuePress 中。
+
+## 使用方法
+
+```bash
+npm i -D @vuepress/plugin-clarity-analytics@next
+```
+
+```ts title=".vuepress/config.ts"
+import { clarityAnalyticsPlugin } from '@vuepress/plugin-clarity-analytics'
+
+export default {
+  plugins: [
+    clarityAnalyticsPlugin({
+      // 配置项
+    }),
+  ],
+}
+```
+
+### 事件上报
+
+本插件可帮助你更好地了解用户跟你的网站的交互。
+
+[支持的功能](https://learn.microsoft.com/en-us/clarity/setup-and-installation/about-clarity#supported-features)
+
+- 访问录制
+- 热点地图
+- 事件和漏斗跟踪
+- 使用 Copilot 聊天和汇总
+
+引入插件后，全局 `clarity()` 函数会挂载到 `window` 对象，可用于 [高级特性](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-api)。
+
+## 选项
+
+### id
+
+- 类型: `string`
+- 必填：是
+- 详情: Clarity Analytics 项目 ID.
+
+### crossOrigin
+
+- 类型: `string`
+- 默认值: `undefined`
+- 详情: `crossorigin` 属性，它提供对 `CORS` 的支持。
diff --git a/plugins/analytics/plugin-clarity-analytics/package.json b/plugins/analytics/plugin-clarity-analytics/package.json
@@ -0,0 +1,53 @@
+{
+  "name": "@vuepress/plugin-clarity-analytics",
+  "version": "2.0.0-rc.112",
+  "description": "VuePress plugin - clarity-analytics",
+  "keywords": [
+    "vuepress-plugin",
+    "vuepress",
+    "plugin",
+    "clarity",
+    "analytics"
+  ],
+  "homepage": "https://ecosystem.vuejs.press/plugins/analytics/clarity-analytics.html",
+  "bugs": {
+    "url": "https://github.com/vuepress/ecosystem/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vuepress/ecosystem.git",
+    "directory": "plugins/analytics/plugin-clarity-analytics"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Zhao Bin",
+    "email": "hi@zhaobc.site",
+    "url": "https://zhaobc.site"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./lib/node/index.js",
+    "./client": "./lib/client/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./lib/node/index.js",
+  "types": "./lib/node/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "bundle": "rollup -c rollup.config.ts --configPlugin esbuild",
+    "clean": "rimraf --glob ./lib ./*.tsbuildinfo"
+  },
+  "dependencies": {
+    "@vuepress/helper": "workspace:*",
+    "vue": "catalog:"
+  },
+  "peerDependencies": {
+    "vuepress": "catalog:"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
diff --git a/plugins/analytics/plugin-clarity-analytics/rollup.config.ts b/plugins/analytics/plugin-clarity-analytics/rollup.config.ts
@@ -0,0 +1,9 @@
+import { rollupBundle } from '../../../scripts/rollup.js'
+
+export default [
+  ...rollupBundle('node/index'),
+  ...rollupBundle({
+    base: 'client',
+    files: ['config', 'index'],
+  }),
+]
diff --git a/plugins/analytics/plugin-clarity-analytics/src/client/composables/index.ts b/plugins/analytics/plugin-clarity-analytics/src/client/composables/index.ts
@@ -0,0 +1 @@
+export * from './useClarityAnalytics.js'
diff --git a/plugins/analytics/plugin-clarity-analytics/src/client/composables/useClarityAnalytics.ts b/plugins/analytics/plugin-clarity-analytics/src/client/composables/useClarityAnalytics.ts
@@ -0,0 +1,39 @@
+import type { ClarityOptions } from '../../shared/index.js'
+
+declare global {
+  interface Window {
+    clarity?: (...args: unknown[]) => void
+  }
+}
+
+/**
+ * Initialize Clarity Analytics tracking
+ *
+ * 初始化 Clarity Analytics 追踪
+ *
+ * @param options - Clarity Analytics options
+ *
+ * @description Injects Clarity tracking script and configures tracking behavior.
+ * The global `clarity()` function will be available for custom event tracking.
+ *
+ * 注入 Clarity 追踪脚本并配置追踪行为。
+ * 全局 `clarity` 函数可用于自定义事件追踪。
+ *
+ * @see https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-api
+ */
+export const useClarityAnalytics = ({
+  id,
+  crossOrigin,
+}: ClarityOptions): void => {
+  // avoid duplicated import
+  if ('clarity' in window) return
+
+  const script = document.createElement('script')
+  script.src = `https://www.clarity.ms/tag/${id}`
+  script.async = true
+  if (crossOrigin !== undefined) {
+    script.crossOrigin = crossOrigin
+  }
+
+  document.head.appendChild(script)
+}
diff --git a/plugins/analytics/plugin-clarity-analytics/src/client/config.ts b/plugins/analytics/plugin-clarity-analytics/src/client/config.ts
@@ -0,0 +1,12 @@
+import { defineClientConfig } from 'vuepress/client'
+import type { ClarityOptions } from '../shared/index.js'
+import { useClarityAnalytics } from './composables/index.js'
+
+declare const __CLARITY_OPTIONS__: ClarityOptions
+
+export default defineClientConfig({
+  setup() {
+    if (__VUEPRESS_SSR__) return
+    useClarityAnalytics(__CLARITY_OPTIONS__)
+  },
+})
diff --git a/plugins/analytics/plugin-clarity-analytics/src/client/index.ts b/plugins/analytics/plugin-clarity-analytics/src/client/index.ts
@@ -0,0 +1 @@
+export * from './composables/index.js'
diff --git a/plugins/analytics/plugin-clarity-analytics/src/node/clarityAnalyticsPlugin.ts b/plugins/analytics/plugin-clarity-analytics/src/node/clarityAnalyticsPlugin.ts
@@ -0,0 +1,66 @@
+import { Logger } from '@vuepress/helper'
+import type { Plugin, PluginObject } from 'vuepress/core'
+import { colors, getDirname, path } from 'vuepress/utils'
+import type { ClarityOptions } from '../shared/index.js'
+
+const __dirname = import.meta.dirname || getDirname(import.meta.url)
+
+const PLUGIN_NAME = '@vuepress/plugin-clarity-analytics'
+
+const logger = new Logger(PLUGIN_NAME)
+
+/**
+ * Clarity Analytics plugin for VuePress
+ *
+ * VuePress 的 Clarity Analytics 插件
+ *
+ * @param options - Plugin options
+ * @returns VuePress plugin
+ *
+ * @description Integrates Clarity Analytics tracking into VuePress applications.
+ * Only active in production builds when a valid project ID is provided.
+ *
+ * 集成 Clarity Analytics 追踪到 VuePress 应用中。
+ * 仅在生产构建且提供有效项目 ID 时启用。
+ *
+ * @example
+ * ```ts
+ * import { clarityAnalyticsPlugin } from '@vuepress/plugin-clarity-analytics'
+ *
+ * export default {
+ *   plugins: [
+ *     clarityAnalyticsPlugin({
+ *       id: 'your-project-id',
+ *     })
+ *   ]
+ * }
+ * ```
+ */
+export const clarityAnalyticsPlugin =
+  ({ id, ...options }: ClarityOptions): Plugin =>
+  (app) => {
+    const plugin: PluginObject = {
+      name: PLUGIN_NAME,
+    }
+
+    if (!id) {
+      logger.warn(`${colors.cyan('id')} is required!`)
+
+      return plugin
+    }
+
+    // returns an empty plugin in dev mode when debug mode is not enabled
+    if (app.env.isDev) {
+      return plugin
+    }
+
+    return {
+      ...plugin,
+
+      define: {
+        __CLARITY_OPTIONS__: { id, ...options },
+      },
+
+      clientConfigFile: path.resolve(__dirname, '../client/config.js'),
+    }
+  }
diff --git a/plugins/analytics/plugin-clarity-analytics/src/node/index.ts b/plugins/analytics/plugin-clarity-analytics/src/node/index.ts
@@ -0,0 +1,2 @@
+export * from './clarityAnalyticsPlugin.js'
+export type { ClarityOptions as ClarityPluginOptions } from '../shared/index.js'
diff --git a/plugins/analytics/plugin-clarity-analytics/src/shared/index.ts b/plugins/analytics/plugin-clarity-analytics/src/shared/index.ts
@@ -0,0 +1 @@
+export type * from './options.js'
diff --git a/plugins/analytics/plugin-clarity-analytics/src/shared/options.ts b/plugins/analytics/plugin-clarity-analytics/src/shared/options.ts
@@ -0,0 +1,29 @@
+/**
+ * Options for @vuepress/plugin-clarity-analytics
+ *
+ * @vuepress/plugin-clarity-analytics 插件选项
+ */
+export interface ClarityOptions {
+  /**
+   * Clarity project ID
+   *
+   * Clarity 项目 ID
+   *
+   * @description The project ID from your Clarity dashboard
+   *
+   * 从 Clarity 仪表板获取的网站 ID
+   */
+  id: string
+
+  /**
+   * The crossorigin attribute for clarity script.
+   *
+   * clarity script 的 crossorigin 属性
+   *
+   * @description provides support for CORS, defining how the element handles cross-origin requests,
+   * thereby enabling the configuration of the CORS requests for the element's fetched data.
+   *
+   * 提供对 CORS 的支持，定义该元素如何处理跨源请求，从而实现对该元素获取数据的 CORS 请求的配置。
+   */
+  crossOrigin?: '' | 'anonymous' | 'use-credentials'
+}
diff --git a/plugins/analytics/plugin-clarity-analytics/tsconfig.build.json b/plugins/analytics/plugin-clarity-analytics/tsconfig.build.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.build.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./lib",
+    "types": ["vuepress/client-types"]
+  },
+  "include": ["./src"],
+  "references": [{ "path": "../../../tools/helper/tsconfig.build.json" }]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/tsconfig.build.json b/tsconfig.build.json
@@ -10,6 +10,9 @@
     {
       "path": "./plugins/analytics/plugin-baidu-analytics/tsconfig.build.json"
     },
+    {
+      "path": "./plugins/analytics/plugin-clarity-analytics/tsconfig.build.json"
+    },
     {
       "path": "./plugins/analytics/plugin-google-analytics/tsconfig.build.json"
     },

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+export * from './useClarityAnalytics.js'`