VitePress

VitePress has a head option in .vitepress/config.ts that adds tags to every page, which is where the snippet goes. A custom theme is the fallback when you need to load it conditionally at runtime.

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 the numeric ID of your site. If you self-host Rybbit, app.rybbit.io is the domain of your own instance.

Add the snippet to VitePress

Edit .vitepress/config.ts (or .js / .mts) and add the tag to head:

import { defineConfig } from "vitepress";

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

The empty string for defer is intentional. VitePress renders it as a boolean attribute.

To track production only, make head conditional:

const isProd = process.env.NODE_ENV === "production";

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

If you need runtime control, inject the tag from a custom theme. Create or edit .vitepress/theme/index.ts:

import { type Theme } from "vitepress";
import DefaultTheme from "vitepress/theme";

export default {
  extends: DefaultTheme,
  enhanceApp() {
    if (typeof window === "undefined") return;

    const el = document.createElement("script");
    el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
    el.defer = true;
    document.head.appendChild(el);
  },
} satisfies Theme;

The window check keeps the injector out of the server-side build.

VitePress navigates between pages client-side. Rybbit picks up those History API changes as pageviews, so no extra code is needed.

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.

Troubleshooting

Tag missing in vitepress dev: if you used the isProd guard, the tag only renders in vitepress build. Remove the guard to test locally.
Pageviews stop after navigation: check the browser console for errors thrown by other head scripts or theme code; an exception during route change can block Rybbit's listener.

Next steps

Track custom events such as signups, purchases and button clicks.
Identify users to connect sessions to accounts.
Proxy the script through your own domain to bypass ad blockers.
Script attributes let you skip or mask URLs and tag events.

Get your tracking snippet

Add the snippet to VitePress

Verify installation

Troubleshooting

Next steps

On this page