feat: add rybbit analytics to registry (#453)

Author: dankerow

docs/content/scripts/analytics/rybbit-analytics.md

@@ -0,0 +1,164 @@
+---
+title: Rybbit Analytics
+description: Use Rybbit Analytics in your Nuxt app.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/scripts/blob/main/src/runtime/registry/rybbit.ts
+    size: xs
+---
+
+[Rybbit Analytics](https://www.rybbit.io/) is a privacy-focused analytics solution for tracking user activity on your website without compromising your users' privacy.
+
+The simplest way to load Rybbit Analytics globally in your Nuxt App is to use Nuxt config. Alternatively you can directly
+use the [useScriptRybbitAnalytics](#useScriptRybbitAnalytics) composable.
+
+## Loading Globally
+
+If you don't plan to send custom events you can use the [Environment overrides](https://nuxt.com/docs/getting-started/configuration#environment-overrides) to
+disable the script in development.
+
+::code-group
+
+```ts [Always enabled]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      rybbitAnalytics: {
+        siteId: 'YOUR_SITE_ID'
+      }
+    }
+  }
+})
+```
+
+```ts [Production only]
+export default defineNuxtConfig({
+  $production: {
+    scripts: {
+      registry: {
+        rybbitAnalytics: {
+          siteId: 'YOUR_SITE_ID',
+        }
+      }
+    }
+  }
+})
+```
+
+```ts [Environment Variables]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      rybbitAnalytics: true,
+    }
+  },
+  // you need to provide a runtime config to access the environment variables
+  runtimeConfig: {
+    public: {
+      scripts: {
+        rybbitAnalytics: {
+          // .env
+          // NUXT_PUBLIC_SCRIPTS_RYBBIT_ANALYTICS_SITE_ID=<your-site-id>
+          siteId: ''
+        },
+      },
+    },
+  },
+})
+```
+
+::
+
+## useScriptRybbitAnalytics
+
+The `useScriptRybbitAnalytics` composable lets you have fine-grain control over when and how Rybbit Analytics is loaded on your site.
+
+```ts
+const rybbit = useScriptRybbitAnalytics({
+  siteId: 'YOUR_SITE_ID'
+})
+```
+
+Please follow the [Registry Scripts](/docs/guides/registry-scripts) guide to learn more about advanced usage.
+
+### Self-hosted Rybbit Analytics
+
+If you are using a self-hosted version of Rybbit Analytics, you can provide a custom script source:
+
+```ts
+useScriptRybbitAnalytics({
+  scriptInput: {
+    src: 'https://your-rybbit-instance.com/api/script.js'
+  }
+  siteId: 'YOUR_SITE_ID'
+})
+```
+
+### RybbitAnalyticsApi
+
+```ts
+export interface RybbitAnalyticsApi {
+  pageview: () => void
+  event: (eventName: string, properties?: Record<string, any>) => void
+}
+```
+
+### Config Schema
+
+You must provide the options when setting up the script for the first time.
+
+```ts
+export const RybbitAnalyticsOptions = object({
+  siteId: string(), // required
+  trackSpa: optional(boolean()),
+  trackQuery: optional(boolean()),
+  skipPatterns: optional(array(string())),
+  maskPatterns: optional(array(string())),
+  debounce: optional(number())
+})
+```
+
+#### Configuration Options
+
+- `siteId` (required): Your Rybbit Analytics site ID
+- `trackSpa`: Set to `false` to disable automatic pageview tracking for single page applications
+- `trackQuery`: Set to `false` to disable tracking of URL query strings
+- `skipPatterns`: Array of URL path patterns to ignore
+- `maskPatterns`: Array of URL path patterns to mask for privacy
+- `debounce`: Delay in milliseconds before tracking a pageview after URL changes
+
+## Example
+
+Using Rybbit Analytics only in production while tracking custom events.
+
+::code-group
+
+```vue [EventTracking.vue]
+<script setup lang="ts">
+const { proxy } = useScriptRybbitAnalytics()
+
+// Track a pageview manually
+function trackPage() {
+  proxy.rybbit.pageview()
+}
+
+// Track a custom event
+function trackEvent() {
+  proxy.rybbit.event('button_click', { buttonId: 'signup' })
+}
+</script>
+
+<template>
+  <div>
+    <button @click="trackPage">
+      Track Custom Page
+    </button>
+    <button @click="trackEvent">
+      Track Custom Event
+    </button>
+  </div>
+</template>
+```
+
+::

src/registry.ts

@@ -58,6 +58,15 @@ export async function registry(resolve?: (path: string, opts?: ResolvePathOption
         from: await resolve('./runtime/registry/matomo-analytics'),
       },
     },
+    {
+      label: 'Rybbit Analytics',
+      category: 'analytics',
+      logo: `https://www.rybbit.io/rybbit.png`,
+      import: {
+        name: 'useScriptRybbitAnalytics',
+        from: await resolve('./runtime/registry/rybbit-analytics'),
+      },
+    },
     {
       label: 'Segment',
       scriptBundling: (options?: SegmentInput) => {

src/runtime/registry/rybbit-analytics.ts

@@ -0,0 +1,47 @@
+import { useRegistryScript } from '../utils'
+import { array, boolean, number, object, optional, string } from '#nuxt-scripts-validator'
+import type { RegistryScriptInput } from '#nuxt-scripts/types'
+
+export const RybbitAnalyticsOptions = object({
+  siteId: string(), // required
+  trackSpa: optional(boolean()),
+  trackQuery: optional(boolean()),
+  skipPatterns: optional(array(string())),
+  maskPatterns: optional(array(string())),
+  debounce: optional(number()),
+})
+
+export type RybbitAnalyticsInput = RegistryScriptInput<typeof RybbitAnalyticsOptions, false>
+
+export interface RybbitAnalyticsApi {
+  pageview: () => void
+  event: (eventName: string, properties?: Record<string, any>) => void
+}
+
+declare global {
+  interface Window {
+    rybbit: RybbitAnalyticsApi
+  }
+}
+
+export function useScriptRybbitAnalytics<T extends RybbitAnalyticsApi>(_options?: RybbitAnalyticsInput) {
+  return useRegistryScript<T, typeof RybbitAnalyticsOptions>('rybbitAnalytics', (options) => {
+    return {
+      scriptInput: {
+        'src': 'https://app.rybbit.io/api/script.js',
+        'data-site-id': options?.siteId,
+        'data-track-spa': options?.trackSpa,
+        'data-track-query': options?.trackQuery,
+        'data-skip-patterns': options?.skipPatterns ? JSON.stringify(options.skipPatterns) : undefined,
+        'data-mask-patterns': options?.maskPatterns ? JSON.stringify(options.maskPatterns) : undefined,
+        'data-debounce': options?.debounce ? options.debounce.toString() : undefined,
+      },
+      schema: import.meta.dev ? RybbitAnalyticsOptions : undefined,
+      scriptOptions: {
+        use() {
+          return { rybbit: window.rybbit }
+        },
+      },
+    }
+  }, _options)
+}

src/runtime/types.ts

@@ -27,6 +27,7 @@ import type { CrispInput } from './registry/crisp'
 import type { GoogleAnalyticsInput } from './registry/google-analytics'
 import type { GoogleTagManagerInput } from './registry/google-tag-manager'
 import type { UmamiAnalyticsInput } from './registry/umami-analytics'
+import type { RybbitAnalyticsInput } from './registry/rybbit-analytics'
 import { object } from '#nuxt-scripts-validator'
 
 export type WarmupStrategy = false | 'preload' | 'preconnect' | 'dns-prefetch'
@@ -139,6 +140,7 @@ export interface ScriptRegistry {
   hotjar?: HotjarInput
   intercom?: IntercomInput
   matomoAnalytics?: MatomoAnalyticsInput
+  rybbitAnalytics?: RybbitAnalyticsInput
   segment?: SegmentInput
   stripe?: StripeInput
   xPixel?: XPixelInput