Installation
npm install @databuddy/sdk
Setup
Add the <Databuddy /> component to your root layout:
// app/layout.tsx (Next.js App Router)
import { Databuddy } from '@databuddy/sdk/react';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Databuddy
clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID}
trackWebVitals
trackErrors
trackScrollDepth
/>
</body>
</html>
);
}
Configuration Props
Website ID from dashboard (auto-detected from NEXT_PUBLIC_DATABUDDY_CLIENT_ID if not provided)
Tracking endpoint URL. Default: https://basket.databuddy.cc
Enable Core Web Vitals tracking (LCP, FID, CLS)
Automatically track JavaScript errors
Track scroll depth (25%, 50%, 75%, 100%)
Track clicks on external links
Disable tracking (useful for development)
Using Tracking Functions
Import and use tracking functions in any component:
import { track, flush } from '@databuddy/sdk';
function CheckoutButton() {
const handleClick = () => {
track('checkout_clicked', {
cartSize: 3,
cartValue: 149.97
});
};
return <button onClick={handleClick}>Checkout</button>;
}
React Component Example
import { useEffect } from 'react';
import { track } from '@databuddy/sdk';
function ProductPage({ product }) {
useEffect(() => {
// Track product view
track('product_viewed', {
productId: product.id,
productName: product.name,
price: product.price,
category: product.category
});
}, [product.id]);
return (
<div>
<h1>{product.name}</h1>
<button onClick={() => {
track('add_to_cart', {
productId: product.id,
price: product.price
});
addToCart(product);
}}>
Add to Cart
</button>
</div>
);
}
Next.js Pages Router
For Next.js Pages Router, add to _app.tsx:
// pages/_app.tsx
import { Databuddy } from '@databuddy/sdk/react';
import type { AppProps } from 'next/app';
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<Component {...pageProps} />
<Databuddy
trackWebVitals
trackErrors
/>
</>
);
}
Environment Variables
Create a .env.local file:
NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your_website_id
clientId prop is not provided.
Disable in Development
<Databuddy
disabled={process.env.NODE_ENV === 'development'}
trackWebVitals
/>
TypeScript Support
The SDK includes full TypeScript definitions:
import { track, getAnonymousId, flush } from '@databuddy/sdk';
import type { DatabuddyTracker } from '@databuddy/sdk';
// Type-safe event tracking
interface PurchaseEvent {
orderId: string;
total: number;
items: number;
}
function trackPurchase(data: PurchaseEvent) {
track('purchase', data);
flush();
}