Nuxt.js

Nuxt has two ways to load Rybbit: the Nuxt Scripts module, which ships a first-class Rybbit registry entry with a typed composable, or the app.head.script array in nuxt.config.ts.

Get your tracking snippet

In your Rybbit dashboard, open Site Settings → Tracking Script and copy your snippet. It looks like this:

<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

YOUR_SITE_ID is your site's ID, a 12-character string such as a1b2c3d4e5f6. Older sites may use a numeric ID, which still works. If you self-host Rybbit, app.rybbit.io is the domain of your own instance.

Add the snippet to Nuxt

Install the module. This adds @nuxt/scripts to the modules array in your nuxt.config:

npx nuxi module add scripts

nuxt.config.ts

export default defineNuxtConfig({
  modules: ["@nuxt/scripts"],
  scripts: {
    registry: {
      rybbitAnalytics: {
        siteId: "YOUR_SITE_ID",
        trigger: "onNuxtReady",
      },
    },
  },
});

Options:

siteId (required): your Rybbit site ID.
analyticsHost: script and API host for a self-hosted instance, for example https://your-instance.com/api.
skipPatterns, maskPatterns, debounce: passed to the script as the matching script attributes. The module drops debounce: 0, so the script keeps its 500 ms default; use the nuxt.config head method if you need to turn debouncing off.

The module also accepts autoTrackPageview, trackSpa, trackQuery, trackOutbound, trackErrors, sessionReplay and webVitals, but the current script ignores them. Turn those features on or off under Site Settings → Tracking in your Rybbit dashboard instead.

To keep the site ID out of source control, leave siteId unset and provide NUXT_PUBLIC_SCRIPTS_RYBBIT_ANALYTICS_SITE_ID in the environment; Nuxt Scripts reads it at runtime.

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

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
          defer: true,
        },
      ],
    },
  },
});

On Nuxt 2 the array is head.script at the top level of nuxt.config.js, with the same entry.

Verify installation

Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

If nothing shows up:

View the page source and search for script.js?siteId= to confirm the snippet is on the page.
Open the browser Network tab and check that script.js returns 200 and that POST requests go to /api/track.
Disable ad blockers, or set up a proxy so the script loads from your own domain.
See the script troubleshooting guide for other common causes.

Track custom events

With Nuxt Scripts, use the useScriptRybbitAnalytics composable. Its proxy queues calls until the script is ready, so it is safe to call immediately:

components/ActionButton.vue

<template>
  <button @click="handleAction">Track action</button>
</template>

<script setup>
const { proxy } = useScriptRybbitAnalytics();

function handleAction() {
  proxy.event("nuxt_interaction", { detail: "User clicked the action button" });
}
</script>

With the app.head.script method, call window.rybbit directly and guard it with import.meta.client, since components also run on the server (on Nuxt 2 use process.client):