Nuxt Fathom module

Nuxt Fathom

用於整合 Fathom Analytics 的 Nuxt 模組。

特色

⚡ 自動或手動追蹤
📯 自動匯入的 composables
🏷️ 完全類型化的 Fathom API
🦾 支援 SSR
📂 .env 檔案支援

設定

# pnpm
pnpm add -D nuxt-fathom

# npm
npm i -D nuxt-fathom

# yarn
yarn add -D nuxt-fathom

基本用法

將 nuxt-fathom 新增至 Nuxt 設定的 modules 區段，並提供您的 Fathom 網站 ID。

// `nuxt.config.ts`
export default defineNuxtConfig({
  modules: ["nuxt-fathom"],

  fathom: {
    siteId: "FATHOM_SITE_ID",
  },
});

提示：您也可以使用 .env 檔案，而不是 fathom 金鑰。

完成！Fathom Analytics 現在將在您應用程式的用戶端中執行。

組態

所有支援的模組選項都可以使用 Nuxt 設定中的 fathom 金鑰進行配置

export default defineNuxtConfig({
  modules: ['nuxt-fathom'],

  fathom: {
    // The Fathom Analytics site ID to use for tracking
    siteId: string,
    // Additional configuration
    config: {
      manual?: boolean
      auto?: boolean
      honorDNT?: boolean
      canonical?: boolean
      spa?: 'auto' | 'history' | 'hash'
    }
  }
})

執行階段配置

您可以在專案的 .env 檔案中設定所需的選項，而不是在 Nuxt 設定中硬式編碼您的 Fathom Analytics 網站 ID，利用執行階段自動取代的公開執行階段配置值，透過比對執行階段的環境變數。

# Overwrites the `fathom.siteId` module option
NUXT_PUBLIC_FATHOM_SITE_ID=YOUR_SITE_ID

透過此設定，如果您只想設定網站 ID，則可以省略 Nuxt 設定中的 fathom 金鑰。

模組選項

屬性	類型	描述	預設值
`manual`	`boolean`	如果您想要手動控制頁面檢視追蹤。	`false`
`auto`	`boolean`	當 `false` 時，會略過在指令碼載入時自動追蹤頁面檢視。	`true`
`honorDNT`	`boolean`	當 `true` 時，會採用訪客瀏覽器中的 DNT 標頭。	`false`
`canonical`	`boolean`	當 `false` 時，會忽略現有的標準標籤。	`true`
`spa`	`'auto'、'history'、'hash'`	接受以下值之一：auto、history 或 hash (請參閱進階文件)。	`undefined`

Composables

與 Nuxt 3 生態系統中的其他 composables 一樣，它們是自動匯入的，並且可以在您應用程式的元件中使用。

`useFathom`

支援 SSR 的 useFathom composable 提供以下項目的存取權

blockTrackingForMe 方法。
enableTrackingForMe 方法。
isTrackingEnabled 方法。
setSite 方法。
trackEvent 方法。
trackPageview 方法。

它可以使用如下

// Each method is destructurable from the composable
const {
  blockTrackingForMe,
  enableTrackingForMe,
  isTrackingEnabled,
  setSite,
  trackEvent, // The method most likely to be used.
  trackPageview,
} = useFathom();

!注意由於 fathom 實例僅在用戶端中可用，因此在伺服器上執行的任何 useFathom 方法呼叫都不會產生任何作用。

開發

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

# Release new version
pnpm run release

貢獻者

johannschopplich，他的 nuxt-gtag 專案啟發了這個專案。
derrickreimer，他的 fathom-client。