TanStack Start

TanStack Start manages the document head through the root route's head() option, rendered by <HeadContent /> in src/routes/__root.tsx. Add the snippet to the scripts array returned by head() and it is on every route.

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 TanStack Start

Open src/routes/__root.tsx and add a scripts entry to the object returned by head(). <HeadContent /> in the root document renders it as a <script> tag inside <head>:

src/routes/__root.tsx

import type { ReactNode } from "react";
import { Outlet, createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";

export const Route = createRootRoute({
  head: () => ({
    meta: [
      { charSet: "utf-8" },
      { name: "viewport", content: "width=device-width, initial-scale=1" },
      { title: "My App" },
    ],
    scripts: [
      {
        src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
        defer: true,
      },
    ],
  }),
  component: RootComponent,
});

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  );
}

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

Use the scripts key inside head(), not the route-level scripts option: that one renders body scripts through <Scripts />, which also works but loads later. Client-side navigation through <Link> and useNavigate() is tracked automatically as pageviews.

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 route component. Check for window first, because TanStack Start renders routes on the server by default.

src/routes/pricing.tsx

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/pricing")({
  component: Pricing,
});

function Pricing() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("plan_selected", { plan: "pro" });
    }
  };

  return <button onClick={handleClick}>Choose Pro</button>;
}

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.