feat: init umami analytics plugin (#116)

.vscode/settings.json

@@ -44,6 +44,7 @@
     "slugify",
     "tsbuildinfo",
     "twikoo",
+    "umami",
     "unmount",
     "vuejs",
     "vuepress",

docs/.vuepress/configs/navbar/en.ts

@@ -57,6 +57,7 @@ export const navbarEn: NavbarConfig = [
           '/plugins/google-analytics',
           '/plugins/seo/',
           '/plugins/sitemap/',
+          '/plugins/umami-analytics',
         ],
       },
       {

docs/.vuepress/configs/navbar/zh.ts

@@ -61,6 +61,7 @@ export const navbarZh: NavbarConfig = [
           '/zh/plugins/google-analytics',
           '/zh/plugins/seo/',
           '/zh/plugins/sitemap/',
+          '/zh/plugins/umami-analytics',
         ],
       },
       {

docs/.vuepress/configs/sidebar/en.ts

@@ -89,6 +89,7 @@ export const sidebarEn: SidebarConfig = {
         },
         '/plugins/baidu-analytics',
         '/plugins/google-analytics',
+        '/plugins/umami-analytics',
       ],
     },
     {

docs/.vuepress/configs/sidebar/zh.ts

@@ -90,6 +90,7 @@ export const sidebarZh: SidebarConfig = {
         },
         '/zh/plugins/baidu-analytics',
         '/zh/plugins/google-analytics',
+        '/zh/plugins/umami-analytics',
       ],
     },
     {

docs/plugins/umami-analytics.md

@@ -0,0 +1,70 @@
+# umami-analytics
+
+<NpmBadge package="@vuepress/plugin-umami-analytics" />
+
+Integrate [Umami Analytics](https://umami.is/) into VuePress.
+
+## Usage
+
+```bash
+npm i -D @vuepress/plugin-umami-analytics@next
+```
+
+```ts
+import { umamiAnalyticsPlugin } from '@vuepress/plugin-umami-analytics'
+
+export default {
+  plugins: [
+    umamiAnalyticsPlugin({
+      // options
+    }),
+  ],
+}
+```
+
+You can use [Umami Cloud](https://cloud.umami.is/login) or [Self-host Umami](https://umami.is/docs/install).
+
+### Reporting Events
+
+The plugin will automatically report page view events when visiting and switching pages.
+
+Besides, a global `umami` object is available on the `window` object, and you can call `umami.track` for [custom tracker function](https://umami.is/docs/tracker-functions).
+
+## Options
+
+### id
+
+- Type: `string`
+- Details: The website ID in Umami Analytics
+
+### link
+
+- Type: `string`
+- Details: Link of umami analytics script
+
+### autoTrack
+
+- Type: `boolean`
+- Default: `true`
+- Details:
+
+  By default, Umami tracks all pageviews and events for you automatically. You can disable this behavior and track events yourself using the tracker functions.
+
+### cache
+
+- Type: `boolean`
+- Details:
+
+  Cache data to improve the performance of the tracking script.
+
+  Note: This will use session storage so you may need to inform your users.
+
+### domains
+
+- Type: `string[]`
+- Details: Let the tracker only run on specific domains.
+
+### hostUrl
+
+- Type: `string`
+- Details: Location to send data

docs/zh/plugins/umami-analytics.md

@@ -0,0 +1,70 @@
+# umami-analytics
+
+<NpmBadge package="@vuepress/plugin-umami-analytics" />
+
+将 [Umami 统计](https://umami.is/) 集成到 VuePress 中。
+
+## 使用方法
+
+```bash
+npm i -D @vuepress/plugin-umami-analytics@next
+```
+
+```ts
+import { umamiAnalyticsPlugin } from '@vuepress/plugin-umami-analytics'
+
+export default {
+  plugins: [
+    umamiAnalyticsPlugin({
+      // 配置项
+    }),
+  ],
+}
+```
+
+你可以使用 [Umami Cloud](https://cloud.umami.is/login) 或 [自行托管 Umami](https://umami.is/docs/install)。
+
+### 上报事件
+
+插件会在访问和切换页面时自动上报页面浏览事件。
+
+另外，一个全局的 `umami` 对象会被挂载到 `window` 上，你可以使用 `umami.track` 设置 [自定义追踪](https://umami.is/docs/tracker-functions) 。
+
+## 选项
+
+### id
+
+- 类型： `string`
+- 详情： Umami 统计中的网站 ID。
+
+### link
+
+- 类型：`string`
+- 详情：Umami 统计的脚本链接
+
+### autoTrack
+
+- 类型：`boolean`
+- 默认值：`true`
+- 详情：
+
+  默认情况下，Umami 会自动跟踪所有页面浏览量和事件。你可以禁用此行为并使用追踪器功能自行追踪事件。
+
+### cache
+
+- 类型：`boolean`
+- 详情：
+
+  缓存数据以提高追踪脚本的性能。
+
+  注意：这将使用会话存储，因此您可能需要通知您的用户。
+
+### domains
+
+- 类型：`string[]`
+- 详情： 让跟踪器仅在特定的域名上运行。
+
+### hostUrl
+
+- 类型：`string`
+- 详情：发送数据的位置

plugins/plugin-umami-analytics/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@vuepress/plugin-umami-analytics",
+  "version": "2.0.0-rc.26",
+  "description": "VuePress plugin - umami-analytics",
+  "keywords": [
+    "vuepress-plugin",
+    "vuepress",
+    "plugin",
+    "umami",
+    "analytics"
+  ],
+  "homepage": "https://ecosystem.vuejs.press/plugins/umami-analytics.html",
+  "bugs": {
+    "url": "https://github.com/vuepress/ecosystem/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vuepress/ecosystem.git",
+    "directory": "plugins/plugin-umami-analytics"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Mr.Hope",
+    "email": "[email protected]",
+    "url": "https://mister-hope.com"
+  },
+  "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",
+    "clean": "rimraf --glob ./lib ./*.tsbuildinfo"
+  },
+  "dependencies": {
+    "@vuepress/helper": "workspace:~",
+    "vue": "^3.4.26"
+  },
+  "peerDependencies": {
+    "vuepress": "2.0.0-rc.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

plugins/plugin-umami-analytics/src/client/composables/index.ts

@@ -0,0 +1 @@
+export * from './useUmamiAnalytics.js'

plugins/plugin-umami-analytics/src/client/composables/useUmamiAnalytics.ts

@@ -0,0 +1,43 @@
+import type { UmamiOptions } from '../../shared/index.js'
+
+declare global {
+  interface Window {
+    umami: {
+      track: {
+        (payload?: Record<any, any>): void
+        (name: string, data?: Record<any, any>): void
+      }
+    }
+  }
+}
+
+/**
+ * Add umami analytics to the site
+ *
+ * @see https://tongji.umami.com/
+ * @see https://tongji.umami.com/holmes/Analytics/%E7%99%BE%E5%BA%A6%E7%BB%9F%E8%AE%A1%E4%BD%BF%E7%94%A8%E6%89%8B%E5%86%8C
+ * @see https://tongji.umami.com/holmes/Analytics/%E6%8A%80%E6%9C%AF%E6%8E%A5%E5%85%A5%E6%8C%87%E5%8D%97/JS%20API/JS%20API%E6%8A%80%E6%9C%AF%E6%96%87%E6%A1%A3/_trackPageview
+ */
+export const useUmamiAnalytics = ({
+  link = 'https://us.umami.is/script.js',
+  id,
+  domains,
+  autoTrack,
+  cache,
+  hostUrl,
+}: UmamiOptions): void => {
+  // avoid duplicated import
+  if (window.umami) return
+
+  const script = document.createElement('script')
+  script.src = link!
+  script.async = true
+  script.setAttribute('data-website-id', id)
+
+  if (autoTrack === false) script.setAttribute('data-auto-track', 'false')
+  if (cache) script.setAttribute('data-cache', 'true')
+  if (domains) script.setAttribute('data-domains', domains.join(','))
+  if (hostUrl) script.setAttribute('data-hostUrl', hostUrl)
+
+  document.head.appendChild(script)
+}

plugins/plugin-umami-analytics/src/client/config.ts

@@ -0,0 +1,13 @@
+import { defineClientConfig } from 'vuepress/client'
+import type { ClientConfig } from 'vuepress/client'
+import type { UmamiOptions } from '../shared/index.js'
+import { useUmamiAnalytics } from './composables/index.js'
+
+declare const __UMM_OPTIONS__: UmamiOptions
+
+export default defineClientConfig({
+  setup() {
+    if (__VUEPRESS_SSR__) return
+    useUmamiAnalytics(__UMM_OPTIONS__)
+  },
+}) as ClientConfig

plugins/plugin-umami-analytics/src/client/index.ts

@@ -0,0 +1 @@
+export * from './composables/index.js'

plugins/plugin-umami-analytics/src/node/index.ts

@@ -0,0 +1,2 @@
+export * from './umamiAnalyticsPlugin.js'
+export type { UmamiOptions as UmamiPluginOptions } from '../shared/index.js'

plugins/plugin-umami-analytics/src/node/umamiAnalyticsPlugin.ts

@@ -0,0 +1,39 @@
+import { Logger } from '@vuepress/helper'
+import type { Plugin, PluginObject } from 'vuepress/core'
+import { colors, getDirname, path } from 'vuepress/utils'
+import type { UmamiOptions } from '../shared/index.js'
+
+const __dirname = getDirname(import.meta.url)
+
+const PLUGIN_NAME = '@vuepress/plugin-umami-analytics'
+
+const logger = new Logger(PLUGIN_NAME)
+
+export const umamiAnalyticsPlugin =
+  ({ id, ...options }: UmamiOptions): 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: {
+        __UMM_OPTIONS__: { id, ...options },
+      },
+
+      clientConfigFile: path.resolve(__dirname, '../client/config.js'),
+    }
+  }

plugins/plugin-umami-analytics/src/shared/index.ts

@@ -0,0 +1 @@
+export * from './options.js'

plugins/plugin-umami-analytics/src/shared/options.ts

@@ -0,0 +1,52 @@
+/**
+ * Options for @vuepress/plugin-umami-analytics
+ */
+export interface UmamiOptions {
+  /**
+   * The website ID in umami Analytics
+   *
+   * Umami 统计中的网站 ID。
+   */
+  id: string
+
+  /**
+   * Link of umami analytics script
+   *
+   * Umami 统计的脚本链接
+   *
+   * @default 'https://us.umami.is/script.js'
+   */
+  link?: string
+
+  /**
+   * By default, Umami tracks all pageviews and events for you automatically. You can disable this behavior and track events yourself using the tracker functions.
+   *
+   * 默认情况下，Umami 会自动跟踪所有页面浏览量和事件。你可以禁用此行为并使用追踪器功能自行追踪事件。
+   *
+   * @default true
+   */
+  autoTrack?: boolean
+
+  /**
+   * Cache data to improve the performance of the tracking script.
+   *
+   * 缓存数据以提高追踪脚本的性能。
+   */
+  cache?: boolean
+
+  /**
+   * Let the tracker only run on specific domains.
+   *
+   * 让跟踪器仅在特定的域名上运行。
+   */
+  domains?: string[]
+
+  /**
+   * Location to send data
+   *
+   * 发送数据的位置
+   *
+   * @default link
+   */
+  hostUrl?: string
+}