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.

Start with pageviews and one custom event, then use the same data for goals and funnels. The Free plan includes 10,000 events per month; error tracking starts on Hobby. See current plans and limits.

Before you start

1. Create a free account and add your website in Databuddy.
2. Copy that website's Client ID from its tracking setup. This is a public identifier; keep server API keys out of browser code.
3. Add the Client ID to .env.local at your Next.js project root, then restart your dev server:

NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id

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!}
        />
        {children}
      </body>
    </html>
  );
}

The SDK's React entry point includes the client boundary, so your root layout can stay a Server Component. Custom event handlers belong in a Client Component, as shown below.

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!}
      />
      <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
          crossOrigin="anonymous"
          data-client-id={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID}
          src="https://cdn.databuddy.cc/databuddy.js"
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

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

Optional errors and Web Vitals

Add trackWebVitals to the React component to collect performance measurements. Add trackErrors if your plan includes error tracking. Both are off by default, and the collected measurements count toward your event allowance.

<Databuddy
  clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
  trackWebVitals
  trackErrors
/>

For the script tag, the equivalent attributes are data-track-web-vitals and data-track-errors.

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>
  );
}

This records a click, not a completed subscription. Record outcomes such as account creation or payment after the backend confirms success, using the Node SDK. Send each completed outcome from one place so a browser call and server call do not double-count it.

Use stable event names and small properties such as the button location. Do not send emails, passwords, tokens, or entire form values.

Verify your first events

Verify on your deployed site. For a local test, the standard tracker skips localhost: temporarily add debug to <Databuddy /> to load the debug bundle, or use https://cdn.databuddy.cc/databuddy-debug.js in your script tag. Use a separate Databuddy website and Client ID for local test data, and remove debug mode before deploying.

1. Open your site and use a client-side link to visit a second page.
2. In the browser Network tab, confirm the Databuddy script loads from cdn.databuddy.cc and requests reach basket.databuddy.cc. Events are batched, so allow a few seconds for delivery.
3. Open that website in Databuddy and check for your two pageviews. Check the same date range and website as your test.
4. Trigger the custom event once and confirm its name appears on the Events page. A successful pageview does not prove your custom event is instrumented.

Databuddy DevTools can help inspect the tracker and custom events while you develop.

Production Setup

Add NEXT_PUBLIC_DATABUDDY_CLIENT_ID to your deployment provider before building. On Vercel, choose the deployment environments that should collect data. Next.js embeds public environment variables at build time, so rebuild and redeploy after changing the Client ID.

To avoid test data, disable tracking outside production:

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

NODE_ENV is also production for many preview deployments. If previews should stay out of production analytics, use your deployment provider's environment indicator for disabled, or give previews a separate Databuddy website and Client ID.

Replace an existing tracker

1. Install Databuddy once and verify pageviews and one important event before removing the old tracker.
2. Write down what each existing conversion means. Keep a button click separate from a completed signup, and send the completed event only after success.
3. Recreate the goals and funnels you need in Databuddy. Confirm that their paths and event names match the events you just verified.
4. Remove the old provider's script and manual route listeners when you are ready to switch. Remove any duplicate Databuddy script added through a tag manager or another layout.

If you briefly run both providers, compare the same dates and definitions. Different session, consent, and bot-filtering rules can produce different totals; an exact count match is not a setup requirement.

Troubleshooting

No data in the dashboard

1. Confirm NEXT_PUBLIC_DATABUDDY_CLIENT_ID is set and matches the website in Databuddy.
2. Check the browser Network tab for requests to basket.databuddy.cc.
3. Make sure the component or script is included only once.
4. If disabled is set, confirm it is false in the environment you are testing.
5. Check your site's Content Security Policy and blockers. Allow scripts from https://cdn.databuddy.cc and connections to https://basket.databuddy.cc.
6. For local tests, use the debug bundle as described above. For deployment tests, rebuild after setting the public Client ID.

Pageviews work, but an outcome is missing

Confirm the event call runs after the actual outcome, uses the same website, and is not skipped by an error or redirect. If you send it from a serverless route handler, flush the Node SDK before the handler exits. Check the custom event helpers and server event setup.

Related