How do I install TapCub on Next.js?

Short answer

Add the TapCub script tag once to the head of your root layout (app/layout.tsx, or pages/_document in the pages router). App router navigations are tracked automatically. Call tapcub only in client components; server components and server actions have no tapcub.

Find your site key in Web analytics › Configuration › SDK code.

1. Add the script once

In the app router, put the tag in the head of the root layout:

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <script defer src="https://static.pathclue.com/client.js" data-site="YOUR_SITE_KEY" />
      </head>
      <body>{children}</body>
    </html>
  )
}

In the pages router, put the same tag in the head of pages/_document. Do not print it again from a page component.

The script starts in the browser by itself. Do not create or inject it again from a component; a second insert is ignored.

2. Pageviews and route changes

The first load and later route changes that use browser history are sent automatically. Client navigations in the app router use browser history, so later pageviews are sent without extra code.

To send pageviews yourself, set data-auto-track="false" on the script and call tapcub.pageview() after each route finishes. Note that this also turns off automatic outbound and download clicks, Web Vitals and 404 events. See install on single-page apps.

3. Events and sign-in

tapcub.track('purchase', { revenue: 19.9 });

Call it in a client component (one that starts with "use client"), for example in a click handler. Server components and server actions run where there is no tapcub. Event names are cut at 100 characters; at most 20 properties are kept, keys are cut at 50 characters and string values at 200. Only strings, numbers and booleans are kept as values.

After sign-in, link the visitor to your user ID:

tapcub.login(userId, { plan: 'pro' }, { type: 'login' });

login comes from the identity script, so check that it exists before calling it. More in identify users.

Check it works

Local hostnames such as localhost are skipped by default, which is easy to mistake for a broken install. Test on a deployed preview or the live site, watch the browser network panel for the collect request, then follow check your installation.

Common problems

Not using Next.js? See install TapCub.