chore: deprecate trackLocalhost

nuxt-modules · Feb 5, 2024 · 5e72535 · 5e72535
1 parent 65173ad
commit 5e72535
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -67,14 +67,16 @@ With this setup, you can omit the `plausible` key in your Nuxt configuration.
 
 ## Module Options
 
-| Option                 | Type      | Default                      | Description                                                                                                                                                                                                                                     |
-| ---------------------- | --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `hashMode`             | `boolean` | `false`                      | Whether page views shall be tracked when the URL hash changes. Enable this if your Nuxt app has the `hashMode` router option enabled.                                                                                                           |
-| `trackLocalhost`       | `boolean` | `false`                      | Whether events shall be tracked when running the site locally.                                                                                                                                                                                  |
-| `domain`               | `string`  | `'window.location.hostname'` | The domain to bind tracking event to.                                                                                                                                                                                                           |
-| `apiHost`              | `string`  | `https://plausible.io`       | The API host where the events will be sent to.                                                                                                                                                                                                  |
-| `autoPageviews`        | `boolean` | `true`                       | Track the current page and all further pages automatically. Disable this if you want to manually manage pageview tracking.                                                                                                                      |
-| `autoOutboundTracking` | `boolean` | `false`                      | Track all outbound link clicks automatically. 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. |
+| Option                 | Type       | Default                      | Description                                                                                                                                                                                                                                     |
+| ---------------------- | ---------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`              | `boolean`  | `true`                       | Whether the tracker shall be enabled.                                                                                                                                                                                                           |
+| `hashMode`             | `boolean`  | `false`                      | Whether page views shall be tracked when the URL hash changes. Enable this if your Nuxt app has the `hashMode` router option enabled.                                                                                                           |
+| `ignoredHostnames`     | `string[]` | `undefined`                  | Hostnames to ignore when tracking events.                                                                                                                                                                                                       |
+| `domain`               | `string`   | `'window.location.hostname'` | The domain to bind tracking event to.                                                                                                                                                                                                           |
+| `apiHost`              | `string`   | `https://plausible.io`       | The API host where the events will be sent to.                                                                                                                                                                                                  |
+| `autoPageviews`        | `boolean`  | `true`                       | Track the current page and all further pages automatically. Disable this if you want to manually manage pageview tracking.                                                                                                                      |
+| `autoOutboundTracking` | `boolean`  | `false`                      | Track all outbound link clicks automatically. 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. |
+| `logIgnoredEvents`     | `boolean`  | `false`                      | Log events to the console if they are ignored.                                                                                                                                                                                                  |
 
 ## Composables
 
@@ -129,10 +131,6 @@ function useTrackPageview(
 4. Run `pnpm run dev:prepare`
 5. Start development server using `pnpm run dev`
 
-## Similar Packages
-
-- [vue-plausible](https://github.com/moritzsternemann/vue-plausible), without first-class Nuxt 3 and composables.
-
 ## Credits
 
 - [@Barbapapazes](https://github.com/Barbapapazes) for his [Plausible tracker rewrite](https://github.com/Barbapapazes/plausible-tracker)

diff --git a/src/module.ts b/src/module.ts
@@ -4,6 +4,7 @@ import {
   addPlugin,
   createResolver,
   defineNuxtModule,
+  useLogger,
 } from '@nuxt/kit'
 import { name, version } from '../package.json'
 
@@ -28,16 +29,17 @@ export interface ModuleOptions {
   /**
    * Whether events shall be tracked when running the site locally.
    *
+   * @deprecated Please use `ignoredHostnames` instead.
    * @default false
    */
   trackLocalhost?: boolean
 
   /**
-   * Hostnames to ignore.
+   * Hostnames to ignore when tracking events.
    *
    * @default ['localhost']
    */
-  blackListedDomains?: string[]
+  ignoredHostnames?: string[]
 
   /**
    * The domain to bind tracking event to.
@@ -78,7 +80,7 @@ export interface ModuleOptions {
    *
    * @default false
    */
-  logIgnored?: boolean
+  logIgnoredEvents?: boolean
 }
 
 export default defineNuxtModule<ModuleOptions>({
@@ -98,12 +100,26 @@ export default defineNuxtModule<ModuleOptions>({
     apiHost: 'https://plausible.io',
     autoPageviews: true,
     autoOutboundTracking: false,
-    blackListedDomains: ['localhost'],
-    logIgnored: false,
+    ignoredHostnames: ['localhost'],
+    logIgnoredEvents: false,
   },
   setup(options, nuxt) {
+    const logger = useLogger('plausible')
     const { resolve } = createResolver(import.meta.url)
 
+    // Dedupe `ignoredHostnames` items
+    options.ignoredHostnames = Array.from(new Set(options.ignoredHostnames))
+
+    // Migrate `trackLocalhost` to `ignoredHostnames`
+    if (options.trackLocalhost) {
+      logger.warn(
+        'The `trackLocalhost` option has been deprecated. Please use `ignoredHostnames` instead.',
+      )
+      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>,

diff --git a/src/runtime/plugin.client.ts b/src/runtime/plugin.client.ts
@@ -14,6 +14,8 @@ export default defineNuxtPlugin({
 
     const plausible = createPlausibleTracker({
       ...options,
+      blackListedDomains: options.ignoredHostnames,
+      logIgnored: options.logIgnoredEvents,
       domain: options.domain || window.location.hostname,
     })