TanStack Start

TanStack Start builds the document head from the root route's head() option, rendered by <HeadContent /> in src/routes/__root.tsx. Add the script to the scripts array that head() returns and every route gets it.

Copy your tracking snippet

In OnyxMetric, open your site's Site Settings and copy the tracking script. It looks like this:

<script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>

YOUR_SITE_ID is the numeric ID of your site.

Add the snippet to TanStack Start

In src/routes/__root.tsx, add a scripts entry to the object returned by head(). <HeadContent /> writes it into <head> as a script tag:

src/routes/__root.tsx

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.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID",
        async: 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(). The route-level scripts option renders body scripts through <Scripts />, which works but loads later. <Link> and useNavigate() navigation is tracked automatically.

Check that it works

Load your live site and click through a few pages. Pageviews show up in the OnyxMetric dashboard within seconds.

If nothing arrives:

View the page source and search for script.js?siteId= to confirm the tag is present.
In the browser's Network tab, check that script.js returns 200 and that requests go to /api/track.
Turn off ad blockers, or proxy the script through your own domain.
Read script troubleshooting for other causes.

Track custom events

TanStack Start renders routes on the server by default, so check for window.

src/routes/pricing.tsx

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

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

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

Next steps

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

Copy your tracking snippet

Add the snippet to TanStack Start

Check that it works

Track custom events

Next steps

On this page