Databuddy

Databuddy is a privacy-first analytics platform. This skill covers both the SDK (

@databuddy/sdk

) and the REST API.

External Documentation

For the most up-to-date documentation, fetch: https://databuddy.cc/llms.txt

When to Use This Skill

Use this skill when:

Setting up analytics in React/Next.js/Vue applications
Implementing server-side tracking in Node.js
Adding feature flags to an application
Tracking custom events, errors, or Web Vitals
Integrating LLM observability with Vercel AI SDK
Querying analytics data via the REST API
Building custom dashboards or reports

SDK Entry Points

Import Path	Environment	Description
`@databuddy/sdk`	Browser (Core)	Core tracking utilities and types
`@databuddy/sdk/react`	React/Next.js	React component and hooks
`@databuddy/sdk/node`	Node.js/Server	Server-side tracking with batching
`@databuddy/sdk/vue`	Vue.js	Vue plugin and composables
`@databuddy/sdk/ai/vercel`	AI/LLM	Vercel AI SDK middleware for LLM analytics

Quick Start

React/Next.js

tsx

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
          trackPerformance
        />
      </body>
    </html>
  );
}

Node.js Server-Side

typescript

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

const client = new Databuddy({
  clientId: process.env.DATABUDDY_CLIENT_ID,
  enableBatching: true,
});

await client.track({
  name: "api_call",
  properties: { endpoint: "/users", method: "GET" },
});

// Important: flush before process exit in serverless
await client.flush();

Feature Flags

tsx

import { FlagsProvider, useFlag, useFeature } from "@databuddy/sdk/react";

// Wrap your app
<FlagsProvider clientId="..." user={{ userId: "123" }}>
  <App />
</FlagsProvider>

// In components
function MyComponent() {
  const { on, loading } = useFeature("dark-mode");
  if (loading) return <Skeleton />;
  return on ? <DarkTheme /> : <LightTheme />;
}

LLM Analytics

typescript

import { databuddyLLM } from "@databuddy/sdk/ai/vercel";
import { openai } from "@ai-sdk/openai";

const { track } = databuddyLLM({
  apiKey: process.env.DATABUDDY_API_KEY,
});

const model = track(openai("gpt-4o"));
// All LLM calls are now automatically tracked

Key Configuration Options

Option	Type	Default	Description
`clientId`	`string`	Auto-detect	Project client ID
`disabled`	`boolean`	`false`	Disable all tracking
`trackWebVitals`	`boolean`	`false`	Track Web Vitals metrics
`trackErrors`	`boolean`	`false`	Track JavaScript errors
`trackPerformance`	`boolean`	`true`	Track performance metrics
`enableBatching`	`boolean`	`true`	Enable event batching
`samplingRate`	`number`	`1.0`	Sampling rate (0.0-1.0)
`skipPatterns`	`string[]`	—	Glob patterns to skip tracking

Common Patterns

Disable in Development

tsx

<Databuddy
  disabled={process.env.NODE_ENV === "development"}
  clientId="..."
/>

Skip Sensitive Paths

tsx

<Databuddy
  clientId="..."
  skipPatterns={["/admin/**", "/internal/**"]}
  maskPatterns={["/users/*", "/orders/*"]}
/>

Custom Event Tracking

typescript

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

track("purchase", {
  product_id: "sku-123",
  amount: 99.99,
  currency: "USD",
});

// Node.js
await client.track({
  name: "subscription_renewed",
  properties: { plan: "pro", amount: 29.99 },
});

Global Properties

typescript

// Browser
window.databuddy?.setGlobalProperties({
  plan: "enterprise",
  abVariant: "checkout-v2",
});

// Node.js
client.setGlobalProperties({
  environment: "production",
  version: "1.0.0",
});

REST API

Base URLs

Service	URL	Purpose
Analytics API	`https://api.databuddy.cc/v1`	Query analytics data
Event Tracking	`https://basket.databuddy.cc`	Send custom events

Authentication

Use API key in the

x-api-key

header:

bash

curl -H "x-api-key: dbdy_your_api_key" \
  https://api.databuddy.cc/v1/query/websites

Get API keys from: Dashboard → Organization Settings → API Keys

Query Analytics Data

bash

curl -X POST -H "x-api-key: dbdy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": ["summary", "pages"],
    "preset": "last_30d"
  }' \
  "https://api.databuddy.cc/v1/query?website_id=web_123"

Available Query Types:

Type	Description
`summary`	Overall website metrics and KPIs
`pages`	Page views and performance by URL
`traffic`	Traffic sources and referrers
`browser_name`	Browser usage breakdown
`device_types`	Device category breakdown
`countries`	Visitors by country
`errors`	JavaScript errors
`performance`	Web vitals and load times
`custom_events`	Custom event data

Date Presets:

today

yesterday

last_7d

last_30d

last_90d

this_month

last_month

Send Events via API

bash

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom",
    "name": "purchase",
    "properties": {
      "value": 99.99,
      "currency": "USD"
    }
  }' \
  "https://basket.databuddy.cc/?client_id=web_123"

Batch Events

bash

curl -X POST \
  -H "Content-Type: application/json" \
  -d '[
    {"type": "custom", "name": "event1", "properties": {...}},
    {"type": "custom", "name": "event2", "properties": {...}}
  ]' \
  "https://basket.databuddy.cc/batch?client_id=web_123"

Detailed Documentation

For detailed documentation on specific topics, see:

Core SDK - Browser tracking utilities and types
React Integration - React/Next.js component and hooks
Node.js Integration - Server-side tracking with batching
Feature Flags - Feature flags for all platforms
AI/LLM Tracking - Vercel AI SDK integration
REST API Reference - Full REST API documentation

databuddy

NPX Install

Tags

SKILL.md Content

Databuddy

External Documentation

When to Use This Skill

SDK Entry Points

Quick Start

React/Next.js

Node.js Server-Side

Feature Flags

LLM Analytics

Key Configuration Options

Common Patterns

Disable in Development

Skip Sensitive Paths

Custom Event Tracking

Global Properties

REST API

Base URLs

Authentication

Query Analytics Data

Send Events via API

Batch Events

Detailed Documentation