Next.js

Next.js ships a Script component that controls when a third-party script loads. Render it once in your root layout (App Router) or custom App (Pages Router) so the snippet is on every page.

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

Use next/script with strategy="afterInteractive" instead of a plain <script> tag. The defer attribute from the snippet is not needed; the strategy handles load timing.

app/layout.js

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

pages/_app.js

import Script from "next/script";

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
        strategy="afterInteractive"
      />
    </>
  );
}

Client-side navigation through <Link> and router.push() is tracked automatically as pageviews; 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.

Track custom events

Call window.rybbit.event() from any client component. Guard the call, because the script loads after hydration and components can also render on the server.

components/MyButton.js

"use client";

export default function MyButton({ title }) {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("button_click", { buttonTitle: title });
    }
  };

  return <button onClick={handleClick}>{title}</button>;
}

Troubleshooting

Proxying through your own domain: Next.js rewrites can serve the script and its API from your domain. Follow the Next.js proxy guide; every endpoint must be rewritten, including site/tracking-config, otherwise the script silently falls back to default settings and features such as web vitals and session replay stay off.
Pageviews missing after client-side navigation: this is rare; call window.rybbit.pageview() yourself after the route change only if the default behaviour does not work for you.

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.