How to add analytics to Next.js

There is no npm package to install: the whole integration is a ~5 KB gzipped script that you load from visitrack.app. Because Next.js navigates between pages with the History API, the script's built-in History API listener sees every <Link> navigation and router.push() — you don't need usePathname() effects or a custom _app listener like older analytics setups did.

How to install VisitTrack on Next.js

1. 1

   Step 1: Copy your site id

   Create a site in VisitTrack (or open an existing one). The install step — and later Settings → General — shows your snippet with the real data-site id filled in. Every snippet below uses SITE_ID as the placeholder.

2. 2

   Step 2: App Router: add next/script to the root layout

   Put the <Script> inside <body> in app/layout.tsx, once. Root layouts wrap every route, so this is the only file you touch. Next.js forwards data-* attributes to the final <script> element, which is how the tracker reads your site id.

   app/layout.tsxCopy

   import Script from "next/script";
   
   export default function RootLayout({ children }: { children: React.ReactNode }) {
     return (
       <html lang="en">
         <body>
           {children}
           <Script
             defer
             data-site="SITE_ID"
             src="https://visitrack.app/tracker.js"
             strategy="afterInteractive"
           />
         </body>
       </html>
     );
   }

3. 3

   Step 3: Pages Router: add it to _app.tsx instead

   On the Pages Router, _app.tsx wraps every page. Render the same <Script> next to <Component>. Don't put it in an individual page — it would only load when that page is the first one opened.

   pages/_app.tsxCopy

   import type { AppProps } from "next/app";
   import Script from "next/script";
   
   export default function App({ Component, pageProps }: AppProps) {
     return (
       <>
         <Component {...pageProps} />
         <Script defer data-site="SITE_ID" src="https://visitrack.app/tracker.js" strategy="afterInteractive" />
       </>
     );
   }

4. 4

   Step 4: Allow the script in your Content-Security-Policy

   If you set a CSP (in next.config.js headers or in proxy.ts, which replaced middleware.ts in Next.js 16), add visitrack.app to both script-src and connect-src. If your policy uses a nonce with 'strict-dynamic', host allowlists are ignored — pass the nonce to the <Script> with its nonce prop instead.

   Content-Security-Policy (additions)Copy

   script-src 'self' https://visitrack.app; connect-src 'self' https://visitrack.app;

5. 5

   Step 5: Deploy and open your site

   The tracker ignores localhost on purpose, so next dev traffic never pollutes your numbers. Deploy (a Vercel preview works), open the deployed URL and browse a couple of pages.

How to check VisitTrack is working on Next.js

1. Open the deployed site in a normal browser tab and click between two or three pages using your nav links.
2. In the VisitTrack dashboard, the live view shows you as an active visitor within a few seconds, and the Pages tab lists each route you opened — including ones reached by client-side navigation.
3. In DevTools → Network, filter for collect: every route change sends one POST to visitrack.app/api/collect.
4. Testing on localhost? Temporarily add data-allow-local and data-debug to the <Script>; the console then logs each event and why any was skipped.

Does VisitTrack track Next.js page navigation?

The tracker patches history.pushState and history.replaceState and listens for popstate, so App Router <Link> clicks, router.push(), router.replace() and the back button each produce a pageview. It records the pathname only, and it skips a pageview when the pathname didn't change — so updating search params with router.replace("?tab=billing") doesn't double-count.

Parallel and intercepted routes (a modal at /photo/123 over a feed) count as a pageview for the URL the browser shows, because that's the pathname that changed.

To keep a logged-in area out of your marketing analytics, add data-exclude="/dashboard/*,/settings" to the <Script>. It's checked on every navigation, so moving from the marketing site into the app stops tracking without a reload.

How to track custom events and goals in Next.js

Call window.visitrack(name, props) from a client component after something meaningful succeeds — not on button click, so a failed request never counts. Declare the global once for TypeScript and use optional chaining so nothing throws if an ad blocker stopped the script.

For a plain click with no logic (a CTA, an OAuth button), add data-vt-goal="signup_click" to the element instead — no JavaScript needed. Then turn any event name into a goal in Settings → Goals.

// global.d.ts
declare global {
  interface Window {
    visitrack?: ((name: string, props?: Record<string, unknown>) => void) & {
      identify?: (userId: string, traits?: Record<string, unknown>) => void;
      visitorId?: () => string;
    };
  }
}
export {};

// app/signup/SignupForm.tsx ("use client")
async function onSubmit(values: FormValues) {
  const res = await fetch("/api/signup", { method: "POST", body: JSON.stringify(values) });
  if (!res.ok) return;
  const user = await res.json();
  window.visitrack?.("signup", { method: "email" });
  window.visitrack?.identify?.(user.id, { plan: user.plan });
}

Accounts created in a server action or an OAuth callback can be reported from the server with POST /api/track and a secret API key — see server-side events. Report each signup from one place only.

Revenue attribution on Next.js

Next.js apps usually start Stripe Checkout from a route handler. Read the visitor id in the browser (window.visitrack?.visitorId?.()), send it with the checkout request and set it as client_reference_id on the Checkout Session. VisitTrack then credits each payment to the referrer, campaign and landing page that first brought that visitor in. Full walkthrough: Stripe revenue attribution; other providers are in Revenue attribution.

// app/api/checkout/route.ts
const { priceId, visitorId } = await req.json();
const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: "https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: "https://example.com/pricing",
  client_reference_id: visitorId ?? undefined,
});
return Response.json({ url: session.url });

Script options you might need on Next.js

All optional — add them to the same tag. Full reference: script configuration.

Next.js troubleshooting

Not on Next.js? See all 29 integration guides.