Nuxt.js

This guide explains how to integrate Rybbit with your Nuxt.js application for analytics tracking.

Adding Rybbit via Nuxt Scripts (Recommended)

Nuxt Scripts 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.

Retrieve Your Site ID

Navigate to your Rybbit dashboard to obtain your Site ID. You'll need this for the siteId option below.

Install the Nuxt Scripts module

npx nuxi module add scripts

This installs @nuxt/scripts and adds it to the modules array in your nuxt.config.

Configure Rybbit in `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.

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.

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.

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:

<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.

Modify `nuxt.config.ts` (or `.js`)

For Nuxt 3:

Add the Rybbit script to the app.head.script array in your nuxt.config.ts file:

export default defineNuxtConfig({
  // ... other configurations
  app: {
    head: {
      script: [
        {
          src: 'https://app.rybbit.io/api/script.js',
          defer: true,
          'data-site-id': 'YOUR_SITE_ID', // Replace with your Site ID
        },
      ],
    },
  },
})

For Nuxt 2:

Add the Rybbit script to the head.script array in your nuxt.config.js file:

export default {
  // ... other configurations
  head: {
    // ... other head properties
    script: [
      {
        src: 'https://app.rybbit.io/api/script.js',
        defer: true,
        'data-site-id': 'YOUR_SITE_ID', // Replace with your Site ID
      },
    ],
  },
}

Ensure you replace YOUR_SITE_ID with your actual Site ID from your Rybbit dashboard. This method ensures the script is included in the <head> of all your pages.

Verify Installation

After restarting your Nuxt.js 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 script.js is loaded.

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.

Custom Event Tracking

From any Vue component within your Nuxt.js application, you can track custom events directly via window.rybbit:

<template>
  <button @click="trackCustomEvent">Track Important Action</button>
</template>

<script setup>
function trackCustomEvent() {
  if (process.client && window.rybbit) { // Ensure running on client and rybbit exists
    window.rybbit.event('nuxt_interaction', { detail: 'User clicked important button' });
  }
}
</script>

Using process.client (Nuxt 2) or checking typeof window !== 'undefined' (Nuxt 3, or generally) is good practice before accessing window if your component might render or execute logic on the server side.

On this page