Next.js

Databuddy works with both the App Router and Pages Router. Add it once near the root of your app; page views and client-side route changes are tracked automatically.

Install

bun add @databuddy/sdk

You can also install with npm or yarn:

npm install @databuddy/sdk
yarn add @databuddy/sdk

App Router

Add <Databuddy /> to app/layout.tsx:

import { Databuddy } from "@databuddy/sdk/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Databuddy
          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
          trackPerformance
          trackWebVitals
          trackErrors
        />
        {children}
      </body>
    </html>
  );
}

Add your Client ID to .env.local:

NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id

Pages Router

Add <Databuddy /> to pages/_app.tsx:

import { Databuddy } from "@databuddy/sdk/react";
import type { AppProps } from "next/app";

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <>
      <Databuddy
        clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
        trackPerformance
        trackWebVitals
        trackErrors
      />
      <Component {...pageProps} />
    </>
  );
}

Databuddy sends the first page view when it loads and listens for route changes. Do not add your own router.events or usePathname screen-view tracking unless you intentionally disabled Databuddy's automatic route tracking.

Script Tag Setup

If you prefer not to use the React component, add the script in pages/_document.tsx:

import { Head, Html, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <script
          async
          data-client-id={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID}
          data-track-errors
          data-track-performance
          data-track-web-vitals
          src="https://cdn.databuddy.cc/databuddy.js"
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Use either the React component or the script tag, not both.

Track Custom Events

Use the SDK helper from client components:

"use client";

import { track } from "@databuddy/sdk";

export function SubscribeButton() {
  return (
    <button
      onClick={() =>
        track("subscribe_clicked", {
          location: "header",
        })
      }
      type="button"
    >
      Subscribe
    </button>
  );
}

For server-side events from route handlers, use the Node SDK instead of the browser tracker.

Production Setup

Add NEXT_PUBLIC_DATABUDDY_CLIENT_ID to your deployment provider. On Vercel, set it in Project Settings → Environment Variables for production and preview environments.

To avoid test data, disable tracking outside production:

<Databuddy
  clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
  disabled={process.env.NODE_ENV !== "production"}
  trackErrors
  trackPerformance
  trackWebVitals
/>

Troubleshooting

No data in the dashboard

Confirm NEXT_PUBLIC_DATABUDDY_CLIENT_ID is set and matches the website in Databuddy.
Check the browser Network tab for requests to basket.databuddy.cc.
Make sure the component or script is included only once.
If disabled is set, confirm it is false in the environment you are testing.