feat!: migrate to @plausible-analytics/tracker

Author: johannschopplich

package.json

@@ -39,8 +39,8 @@
     "release": "bumpp"
   },
   "dependencies": {
-    "@barbapapazes/plausible-tracker": "^0.5.6",
     "@nuxt/kit": "^4.3.1",
+    "@plausible-analytics/tracker": "^0.4.4",
     "defu": "^6.1.4",
     "ufo": "^1.6.3"
   },

pnpm-lock.yaml

@@ -4,7 +4,6 @@ import {
   addServerHandler,
   createResolver,
   defineNuxtModule,
-  useLogger,
 } from '@nuxt/kit'
 import { defu } from 'defu'
 import { joinURL, withLeadingSlash } from 'ufo'
@@ -30,14 +29,6 @@ export interface ModuleOptions {
    */
   hashMode?: boolean
 
-  /**
-   * Whether events shall be tracked when running the site locally.
-   *
-   * @deprecated Please use `ignoredHostnames` instead.
-   * @default false
-   */
-  trackLocalhost?: boolean
-
   /**
    * Hostnames to ignore when tracking events.
    *
@@ -80,12 +71,30 @@ export interface ModuleOptions {
    * Track all outbound link clicks automatically.
    *
    * @remarks
-   * If enabled, a [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) automagically detects link nodes throughout the application and binds `click` events to them.
+   * If enabled, outbound link clicks are tracked automatically.
    *
    * @default false
    */
   autoOutboundTracking?: boolean
 
+  /**
+   * Track file downloads automatically.
+   *
+   * @remarks
+   * When enabled, clicks on links to common file types are tracked as `File Download` events.
+   * Pass an object with `fileExtensions` to customize which file types are tracked.
+   *
+   * @default false
+   */
+  fileDownloads?: boolean | { fileExtensions: string[] }
+
+  /**
+   * Track form submissions automatically.
+   *
+   * @default false
+   */
+  formSubmissions?: boolean
+
   /**
    * Log events to the console if they are ignored.
    *
@@ -126,16 +135,16 @@ export default defineNuxtModule<ModuleOptions>({
     domain: '',
     ignoredHostnames: undefined,
     ignoreSubDomains: false,
-    trackLocalhost: undefined,
     apiHost: 'https://plausible.io',
     autoPageviews: true,
     autoOutboundTracking: false,
+    fileDownloads: false,
+    formSubmissions: false,
     logIgnoredEvents: false,
     proxy: false,
     proxyBaseEndpoint: '/_plausible',
   },
   setup(options, nuxt) {
-    const logger = useLogger('plausible')
     const { resolve } = createResolver(import.meta.url)
 
     // Set default hostnames if `ignoredHostnames` is not set
@@ -144,16 +153,6 @@ export default defineNuxtModule<ModuleOptions>({
     // Dedupe `ignoredHostnames` items
     options.ignoredHostnames = Array.from(new Set(options.ignoredHostnames))
 
-    if (options.trackLocalhost !== undefined) {
-      logger.warn('The `trackLocalhost` option has been deprecated. Please use `ignoredHostnames` instead.')
-    }
-    // Migrate `trackLocalhost` to `ignoredHostnames`
-    else if (options.trackLocalhost) {
-      options.ignoredHostnames = options.ignoredHostnames.filter(
-        domain => domain !== 'localhost',
-      )
-    }
-
     // Add module options to public runtime config
     nuxt.options.runtimeConfig.public.plausible = defu(
       nuxt.options.runtimeConfig.public.plausible as Required<ModuleOptions>,
@@ -191,24 +190,6 @@ export default defineNuxtModule<ModuleOptions>({
       mode: 'client',
     })
 
-    // Split plugins to reduce bundle size
-
-    if (options.autoPageviews) {
-      addPlugin({
-        src: resolve('runtime/plugin-auto-pageviews.client'),
-        mode: 'client',
-        order: 1,
-      })
-    }
-
-    if (options.autoOutboundTracking) {
-      addPlugin({
-        src: resolve('runtime/plugin-auto-outbound-tracking.client'),
-        mode: 'client',
-        order: 2,
-      })
-    }
-
     // Add preconnect link when proxy is not used
     if (!options.proxy) {
       addPlugin({

src/module.ts

@@ -1,8 +1,4 @@
-import type {
-  EventName,
-  EventOptions,
-  Plausible,
-} from '@barbapapazes/plausible-tracker'
+import type { PlausibleEventOptions } from '@plausible-analytics/tracker'
 import { useNuxtApp } from '#imports'
 
 /**
@@ -18,8 +14,8 @@ import { useNuxtApp } from '#imports'
  * // Tracks the `Download` goal passing a `method` property.
  * useTrackEvent('Download', { props: { method: 'HTTP' } })
  */
-export function useTrackEvent(eventName: EventName, options?: EventOptions) {
+export function useTrackEvent(eventName: string, options?: PlausibleEventOptions) {
   if (import.meta.client) {
-    ;(useNuxtApp().$plausible as Plausible)?.trackEvent(eventName, options)
+    useNuxtApp().$plausible?.trackEvent(eventName, options)
   }
 }

src/runtime/composables/useTrackEvent.ts

@@ -1,4 +1,4 @@
-import type { EventOptions, Plausible } from '@barbapapazes/plausible-tracker'
+import type { PlausibleEventOptions } from '@plausible-analytics/tracker'
 import { useNuxtApp } from '#imports'
 
 /**
@@ -10,8 +10,8 @@ import { useNuxtApp } from '#imports'
  * @example
  * useTrackPageview()
  */
-export function useTrackPageview(options?: EventOptions) {
+export function useTrackPageview(options?: PlausibleEventOptions) {
   if (import.meta.client) {
-    ;(useNuxtApp().$plausible as Plausible)?.trackPageview(options)
+    useNuxtApp().$plausible?.trackPageview(options)
   }
 }

src/runtime/composables/useTrackPageview.ts

@@ -1,26 +1,66 @@
+import type { PlausibleEventOptions, PlausibleRequestPayload } from '@plausible-analytics/tracker'
 import type {} from 'nuxt/app'
+import type { ModuleOptions } from '../module'
 import { defineNuxtPlugin, useRuntimeConfig } from '#imports'
-import { createPlausibleTracker } from '@barbapapazes/plausible-tracker'
+import { init, track } from '@plausible-analytics/tracker'
+import { joinURL } from 'ufo'
 
 export default defineNuxtPlugin({
   name: 'plausible',
   setup() {
-    const { plausible: options } = useRuntimeConfig().public
+    const { plausible: options } = useRuntimeConfig().public as { plausible: Required<ModuleOptions> }
 
     if (!options.enabled)
       return
 
-    const plausible = createPlausibleTracker({
-      ...options,
-      logIgnored: options.logIgnoredEvents,
+    const ignoredHostnames = options.ignoredHostnames ?? []
+
+    init({
       domain: options.domain || window.location.hostname,
-      apiHost: options.proxy ? options.proxyBaseEndpoint : options.apiHost,
+      endpoint: options.proxy
+        ? joinURL(options.proxyBaseEndpoint, 'api/event')
+        : joinURL(options.apiHost, 'api/event'),
+      autoCapturePageviews: options.autoPageviews,
+      hashBasedRouting: options.hashMode,
+      outboundLinks: options.autoOutboundTracking,
+      fileDownloads: options.fileDownloads,
+      formSubmissions: options.formSubmissions,
+      // The tracker's built-in check also covers 127.x.x.x, [::1], and file: protocol
+      captureOnLocalhost: !ignoredHostnames.includes('localhost'),
+      logging: options.logIgnoredEvents,
+      // Handle non-localhost ignored hostnames (e.g. staging/preview domains)
+      transformRequest: buildHostnameFilter(ignoredHostnames, options.ignoreSubDomains),
     })
 
+    const plausible = {
+      trackEvent(eventName: string, eventOptions?: PlausibleEventOptions) {
+        track(eventName, eventOptions ?? {})
+      },
+      trackPageview(eventOptions?: PlausibleEventOptions) {
+        track('pageview', eventOptions ?? {})
+      },
+    }
+
     return {
       provide: {
         plausible,
       },
     }
   },
 })
+
+function buildHostnameFilter(ignoredHostnames: string[], ignoreSubDomains: boolean) {
+  const customIgnoredHostnames = ignoredHostnames.filter(h => h !== 'localhost')
+  if (customIgnoredHostnames.length === 0)
+    return undefined
+
+  return (payload: PlausibleRequestPayload) => {
+    const hostname = window.location.hostname
+    const isIgnored = customIgnoredHostnames.some(ignored =>
+      ignoreSubDomains
+        ? hostname === ignored || hostname.endsWith(`.${ignored}`)
+        : hostname === ignored,
+    )
+    return isIgnored ? null : payload
+  }
+}