Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

Update Nuxt.js integration guide for Rybbit Analytics

Bill Yangf5a768d60e9d
diff --git a/docs/content/docs/guides/vue/nuxt.mdx b/docs/content/docs/guides/vue/nuxt.mdx
index 5bd58985c..cc343235c 100644
--- a/docs/content/docs/guides/vue/nuxt.mdx
+++ b/docs/content/docs/guides/vue/nuxt.mdx
@@ -7,19 +7,91 @@ import { Steps, Step } from 'fumadocs-ui/components/steps'
import { Callout } from 'fumadocs-ui/components/callout'
-This guide explains how to integrate Rybbit with your Nuxt.js application for analytics tracking. Nuxt.js provides a structured way to add external scripts via its configuration.
+This guide explains how to integrate Rybbit with your Nuxt.js application for analytics tracking.
-## Adding Rybbit via Nuxt.js Configuration
+## Adding Rybbit via Nuxt Scripts (Recommended)
-This is the recommended method for Nuxt.js applications.
+[Nuxt Scripts](https://scripts.nuxt.com/scripts/rybbit-analytics) ships a first-class Rybbit Analytics integration. It loads the script optimally, handles SPA route tracking, and gives you a typed composable for custom events. This is the recommended method for Nuxt 3 and Nuxt 4 applications.
<Steps>
<Step>
### Retrieve Your Site ID
-Navigate to your Rybbit dashboard to obtain your Site ID. You'll need this for the `data-site-id` attribute in the script configuration.
+Navigate to your Rybbit dashboard to obtain your Site ID. You'll need this for the `siteId` option below.
</Step>
+<Step>
+### Install the Nuxt Scripts module
+
+```bash
+npx nuxi module add scripts
+```
+
+This installs `@nuxt/scripts` and adds it to the `modules` array in your `nuxt.config`.
+</Step>
+
+<Step>
+### Configure Rybbit in `nuxt.config.ts`
+
+Register Rybbit Analytics under `scripts.registry` and pass your Site ID:
+
+```typescript filename="nuxt.config.ts"
+export default defineNuxtConfig({
+ modules: ['@nuxt/scripts'],
+ scripts: {
+ registry: {
+ rybbitAnalytics: {
+ siteId: 'YOUR_SITE_ID', // Replace with your Site ID
+ trigger: 'onNuxtReady',
+ },
+ },
+ },
+})
+```
+
+Useful options:
+
+- **`siteId`** (required): Your Rybbit site ID.
+- **`autoTrackPageview`**: Track page views automatically (enabled by default).
+- **`trackSpa`**: Track client-side route changes (enabled by default).
+- **`analyticsHost`**: Override the script/API host when using a self-hosted Rybbit instance (e.g. `https://your-instance.com/api`).
+- **`sessionReplay`**, **`webVitals`**, **`trackOutbound`**: Optional features you can enable as needed.
+
+<Callout type="info">
+ You can keep your Site ID out of source control by setting it via environment variable. Nuxt Scripts reads `NUXT_PUBLIC_SCRIPTS_RYBBIT_ANALYTICS_SITE_ID` at runtime, so you can leave `siteId` unset in config and provide it through your environment instead.
+</Callout>
+</Step>
+
+<Step>
+### Verify Installation
+
+After restarting your Nuxt development server or deploying your application, open your Rybbit dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that the Rybbit script is loaded.
+</Step>
+</Steps>
+
+### Custom Event Tracking
+
+Use the `useScriptRybbitAnalytics` composable to track custom events from any component. The returned `proxy` queues calls until the script is ready, so it's safe to call immediately:
+
+```vue
+<template>
+ <button @click="handleAction">Track Important Action</button>
+</template>
+
+<script setup>
+const { proxy } = useScriptRybbitAnalytics()
+
+function handleAction() {
+ proxy.event('nuxt_interaction', { detail: 'User clicked important button' })
+}
+</script>
+```
+
+## Alternative: Adding Rybbit via `app.head.script`
+
+If you'd rather not use the Nuxt Scripts module, you can add the Rybbit script directly through your Nuxt configuration.
+
+<Steps>
<Step>
### Modify `nuxt.config.ts` (or `.js`)
@@ -77,9 +149,9 @@ After restarting your Nuxt.js development server or deploying your application,
**SPA Page View Tracking**: Rybbit's tracking script is designed to automatically detect route changes in Nuxt.js applications and track them as page views. If you find that page views are not being tracked correctly after navigation (which is uncommon for Nuxt), you might need to manually trigger page views using `window.rybbit.pageview()` after each route change. You could use Nuxt's router events or middleware for this if necessary, but test the default behavior first.
</Callout>
-## Custom Event Tracking
+### Custom Event Tracking
-From any Vue component within your Nuxt.js application, you can track custom events:
+From any Vue component within your Nuxt.js application, you can track custom events directly via `window.rybbit`:
```vue
<template>