feat: add Vercel Analytics support

- New useScriptVercelAnalytics composable with track/pageview API
- Queue init matching @vercel/analytics (window.va/window.vaq)
- beforeSend callback for privacy filtering
- FirstParty proxy support (rewrites va.vercel-scripts.com)
- DSN option for non-Vercel deployments
- Documentation, playground page, and E2E test

Author: harlan-zw

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

@@ -0,0 +1,179 @@
+---
+title: Vercel Analytics
+description: Use Vercel Analytics in your Nuxt app.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/scripts/blob/main/src/runtime/registry/vercel-analytics.ts
+    size: xs
+  - label: Vercel Analytics
+    icon: i-simple-icons-vercel
+    to: https://vercel.com/docs/analytics
+    size: xs
+---
+
+[Vercel Analytics](https://vercel.com/docs/analytics) provides lightweight, privacy-friendly web analytics for your Nuxt app. It tracks page views and custom events with zero configuration when deployed on Vercel.
+
+The simplest way to load Vercel Analytics globally in your Nuxt App is to use Nuxt config. Alternatively you can directly
+use the [useScriptVercelAnalytics](#usescriptvercelanalytics) composable.
+
+## Loading Globally
+
+If you'd like to avoid loading the analytics in development, you can use the [Environment overrides](https://nuxt.com/docs/getting-started/configuration#environment-overrides) in your Nuxt config.
+
+::code-group
+
+```ts [Always enabled]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      vercelAnalytics: true,
+    }
+  }
+})
+```
+
+```ts [Production only]
+export default defineNuxtConfig({
+  $production: {
+    scripts: {
+      registry: {
+        vercelAnalytics: true,
+      }
+    }
+  }
+})
+```
+
+```ts [Non-Vercel deployment]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      vercelAnalytics: {
+        dsn: 'YOUR_DSN',
+      }
+    }
+  }
+})
+```
+
+::
+
+### First-Party Mode
+
+When `scripts.firstParty` is enabled, the analytics script is bundled locally and data collection requests are proxied through your server. This prevents ad blockers from blocking analytics and removes sensitive data from third-party requests.
+
+```ts
+export default defineNuxtConfig({
+  scripts: {
+    firstParty: true,
+    registry: {
+      vercelAnalytics: true,
+    }
+  }
+})
+```
+
+## useScriptVercelAnalytics
+
+The `useScriptVercelAnalytics` composable lets you have fine-grain control over when and how Vercel Analytics is loaded on your site.
+
+```ts
+function useScriptVercelAnalytics<T extends VercelAnalyticsApi>(_options?: VercelAnalyticsInput & { beforeSend?: BeforeSend }) {}
+```
+
+Please follow the [Registry Scripts](/docs/guides/registry-scripts) guide to learn more about advanced usage.
+
+The composable comes with the following defaults:
+- **Trigger: Client** Script will load when the Nuxt is hydrating to keep web vital metrics accurate.
+
+### VercelAnalyticsInput
+
+```ts
+export const VercelAnalyticsOptions = object({
+  /**
+   * The DSN of the project to send events to.
+   * Only required when self-hosting or deploying outside of Vercel.
+   */
+  dsn: optional(string()),
+  /**
+   * Whether to disable automatic page view tracking on route changes.
+   * Set to true if you want to manually call pageview().
+   */
+  disableAutoTrack: optional(boolean()),
+  /**
+   * The mode to use for the analytics script.
+   * - `auto` - Automatically detect the environment (default)
+   * - `production` - Always use production script
+   * - `development` - Always use development script (logs to console)
+   */
+  mode: optional(union([literal('auto'), literal('development'), literal('production')])),
+  /**
+   * Whether to enable debug logging in development.
+   * @default true
+   */
+  debug: optional(boolean()),
+})
+```
+
+### VercelAnalyticsApi
+
+```ts
+export interface VercelAnalyticsApi {
+  va: (event: string, properties?: unknown) => void
+  track: (name: string, properties?: Record<string, AllowedPropertyValues>) => void
+  pageview: (options?: { route?: string | null, path?: string }) => void
+}
+```
+
+### BeforeSend
+
+You can pass a `beforeSend` callback to modify or filter events before they're sent. This is useful for stripping sensitive data from URLs.
+
+```ts
+const { proxy } = useScriptVercelAnalytics({
+  beforeSend(event) {
+    // Strip query params from URLs
+    const url = new URL(event.url)
+    url.search = ''
+    return { ...event, url: url.toString() }
+  },
+})
+```
+
+Returning `null` from `beforeSend` will prevent the event from being sent.
+
+## Example
+
+Loading Vercel Analytics through `app.vue` when Nuxt is ready.
+
+```vue [app.vue]
+<script setup lang="ts">
+const { proxy } = useScriptVercelAnalytics({
+  scriptOptions: {
+    trigger: 'onNuxtReady',
+  },
+})
+
+// Track a custom event
+proxy.track('signup', { plan: 'pro' })
+</script>
+```
+
+### Manual Tracking
+
+If you want full control over what gets tracked, disable automatic tracking and call `track` / `pageview` manually.
+
+```vue [app.vue]
+<script setup lang="ts">
+const { proxy } = useScriptVercelAnalytics({
+  disableAutoTrack: true,
+})
+
+// Track custom event
+proxy.track('purchase', { product: 'widget', price: 9.99 })
+
+// Manual pageview
+proxy.pageview({ path: '/custom-page' })
+</script>
+```

playground/pages/third-parties/vercel-analytics/nuxt-scripts.vue

@@ -0,0 +1,39 @@
+<script lang="ts" setup>
+import { ref, useHead } from '#imports'
+
+useHead({
+  title: 'Vercel Analytics',
+})
+
+const { proxy, status } = useScriptVercelAnalytics({
+  scriptOptions: {
+    trigger: 'onNuxtReady',
+  },
+})
+
+const eventTracked = ref(false)
+
+function trackEvent() {
+  proxy.track('button_click', {
+    button: 'demo',
+    page: '/third-parties/vercel-analytics',
+  })
+  eventTracked.value = true
+}
+</script>
+
+<template>
+  <div>
+    <ClientOnly>
+      <div>
+        status: {{ status }}
+      </div>
+      <div v-if="eventTracked">
+        Event tracked!
+      </div>
+    </ClientOnly>
+    <button @click="trackEvent">
+      Track Event
+    </button>
+  </div>
+</template>

src/proxy-configs.ts

@@ -172,6 +172,28 @@ function buildProxyConfig(collectPrefix: string) {
         [`${collectPrefix}/hotjar-insights/**`]: { proxy: 'https://insights.hotjar.com/**' },
       },
     },
+
+    gravatar: {
+      rewrite: [
+        // Hovercards JS and related scripts
+        { from: 'secure.gravatar.com', to: `${collectPrefix}/gravatar` },
+        // Avatar images (used by hovercards internally)
+        { from: 'gravatar.com/avatar', to: `${collectPrefix}/gravatar-avatar` },
+      ],
+      routes: {
+        [`${collectPrefix}/gravatar/**`]: { proxy: 'https://secure.gravatar.com/**' },
+        [`${collectPrefix}/gravatar-avatar/**`]: { proxy: 'https://gravatar.com/avatar/**' },
+      },
+    },
+
+    vercelAnalytics: {
+      rewrite: [
+        { from: 'va.vercel-scripts.com', to: `${collectPrefix}/vercel` },
+      ],
+      routes: {
+        [`${collectPrefix}/vercel/**`]: { proxy: 'https://va.vercel-scripts.com/**' },
+      },
+    },
   } satisfies Record<string, ProxyConfig>
 }
 

src/registry.ts

@@ -40,6 +40,17 @@ export async function registry(resolve?: (path: string, opts?: ResolvePathOption
         from: await resolve('./runtime/registry/cloudflare-web-analytics'),
       },
     },
+    {
+      label: 'Vercel Analytics',
+      src: 'https://va.vercel-scripts.com/v1/script.js',
+      proxy: 'vercelAnalytics',
+      category: 'analytics',
+      logo: `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 512 512"><path d="M256 48L496 464H16z" fill="currentColor"/></svg>`,
+      import: {
+        name: 'useScriptVercelAnalytics',
+        from: await resolve('./runtime/registry/vercel-analytics'),
+      },
+    },
     {
       label: 'PostHog',
       src: false,
@@ -405,5 +416,16 @@ export async function registry(resolve?: (path: string, opts?: ResolvePathOption
         from: await resolve('./runtime/registry/umami-analytics'),
       },
     },
+    {
+      label: 'Gravatar',
+      proxy: 'gravatar',
+      src: 'https://secure.gravatar.com/js/gprofiles.js',
+      category: 'utility',
+      logo: `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 256 256"><circle cx="128" cy="128" r="128" fill="#1d4fc4"/><path d="M128 28c-55.2 0-100 44.8-100 100s44.8 100 100 100 100-44.8 100-100S183.2 28 128 28zm0 180c-44.1 0-80-35.9-80-80s35.9-80 80-80 80 35.9 80 80-35.9 80-80 80z" fill="#fff"/></svg>`,
+      import: {
+        name: 'useScriptGravatar',
+        from: await resolve('./runtime/registry/gravatar'),
+      },
+    },
   ]
 }

src/runtime/registry/vercel-analytics.ts

@@ -0,0 +1,114 @@
+import { useRegistryScript } from '../utils'
+import { boolean, literal, object, optional, string, union } from '#nuxt-scripts-validator'
+import type { RegistryScriptInput } from '#nuxt-scripts/types'
+
+export type AllowedPropertyValues = string | number | boolean | null | undefined
+
+export interface BeforeSendEvent {
+    type: 'pageview' | 'event'
+    url: string
+}
+
+export type BeforeSend = (event: BeforeSendEvent) => BeforeSendEvent | null
+
+export type VercelAnalyticsMode = 'auto' | 'development' | 'production'
+
+export const VercelAnalyticsOptions = object({
+    /**
+     * The DSN of the project to send events to.
+     * Only required when self-hosting or deploying outside of Vercel.
+     */
+    dsn: optional(string()),
+    /**
+     * Whether to disable automatic page view tracking on route changes.
+     * Set to true if you want to manually call pageview().
+     */
+    disableAutoTrack: optional(boolean()),
+    /**
+     * The mode to use for the analytics script.
+     * - `auto` - Automatically detect the environment (default)
+     * - `production` - Always use production script
+     * - `development` - Always use development script (logs to console)
+     */
+    mode: optional(union([literal('auto'), literal('development'), literal('production')])),
+    /**
+     * Whether to enable debug logging in development.
+     * @default true
+     */
+    debug: optional(boolean()),
+})
+
+export type VercelAnalyticsInput = RegistryScriptInput<typeof VercelAnalyticsOptions, false, false, false>
+
+export interface VercelAnalyticsApi {
+    va: (event: string, properties?: unknown) => void
+    track: (name: string, properties?: Record<string, AllowedPropertyValues>) => void
+    pageview: (options?: { route?: string | null, path?: string }) => void
+}
+
+declare global {
+    interface Window {
+        va?: (event: string, properties?: unknown) => void
+        vaq?: [string, unknown?][]
+        vam?: VercelAnalyticsMode
+    }
+}
+
+export function useScriptVercelAnalytics<T extends VercelAnalyticsApi>(_options?: VercelAnalyticsInput & { beforeSend?: BeforeSend }) {
+    return useRegistryScript<T, typeof VercelAnalyticsOptions>('vercelAnalytics', (options) => {
+        const scriptInput: { src: string, defer: boolean, 'data-dsn'?: string, 'data-disable-auto-track'?: string, 'data-debug'?: string } = {
+            src: 'https://va.vercel-scripts.com/v1/script.js',
+            defer: true,
+        }
+
+        if (options?.dsn)
+            scriptInput['data-dsn'] = options.dsn
+        if (options?.disableAutoTrack)
+            scriptInput['data-disable-auto-track'] = '1'
+        if (options?.debug === false)
+            scriptInput['data-debug'] = 'false'
+
+        return {
+            scriptInput,
+            schema: import.meta.dev ? VercelAnalyticsOptions : undefined,
+            scriptOptions: {
+                use: () => ({
+                    va: window.va as VercelAnalyticsApi['va'],
+                    track(name: string, properties?: Record<string, AllowedPropertyValues>) {
+                        if (!properties) {
+                            window.va?.('event', { name })
+                            return
+                        }
+                        // Strip non-primitive values (objects) in production
+                        const cleaned: Record<string, AllowedPropertyValues> = {}
+                        for (const [key, value] of Object.entries(properties)) {
+                            if (typeof value !== 'object' || value === null)
+                                cleaned[key] = value
+                        }
+                        window.va?.('event', { name, data: cleaned })
+                    },
+                    pageview(opts?: { route?: string | null, path?: string }) {
+                        window.va?.('pageview', opts)
+                    },
+                }),
+            },
+            clientInit: import.meta.server
+                ? undefined
+                : () => {
+                    if (window.va) return
+                    // Set up the queue exactly as @vercel/analytics does
+                    window.va = function (...params: [string, unknown?]) {
+                        ; (window.vaq = window.vaq || []).push(params)
+                    }
+                    // Set mode
+                    if (options?.mode && options.mode !== 'auto') {
+                        window.vam = options.mode
+                    }
+                    // Register beforeSend middleware
+                    if (_options?.beforeSend) {
+                        window.va('beforeSend', _options.beforeSend)
+                    }
+                },
+        }
+    }, _options)
+}