This page documents all configuration options across the Databuddy SDK platforms: React, Vue, vanilla JavaScript, and Node.js.

React / Next.js

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

<Databuddy
// Required
clientId="your-client-id"

// API endpoints
apiUrl="https://basket.databuddy.cc"

// Core tracking
trackWebVitals={true}   // opt in; default: false
trackErrors             // default: false
trackOutgoingLinks      // default: false
trackInteractions       // default: true
trackAttributes         // default: false
trackHashChanges        // default: false

// Batching
enableBatching          // default: true
batchSize={10}          // 1-50
batchTimeout={5000}     // ms

// Retries
enableRetries           // default: true
maxRetries={3}
initialRetryDelay={500} // ms

// Sampling
samplingRate={1.0}      // 0.0-1.0

// Privacy
skipPatterns={["/admin/**", "/private/*"]}
maskPatterns={["/users/*", "/orders/**"]}

// Control
disabled={false}
debug={false}
/>

React props reference

Prop	Type	Default	Description
`clientId`	`string`	Auto-detect	Client ID (auto-detects from `NEXT_PUBLIC_DATABUDDY_CLIENT_ID`)
`apiUrl`	`string`	`https://basket.databuddy.cc`	Event endpoint. Set it with `scriptUrl` to serve Databuddy from your own domain
`scriptUrl`	`string`	SDK-pinned, date-versioned CDN URL	Custom script URL
`scriptIntegrity`	`string`	SDK-pinned SHA-384 hash	Integrity hash for a custom `scriptUrl`
`disabled`	`boolean`	`false`	Disable all tracking
`debug`	`boolean`	`false`	Enable debug logging

SDK 3.4 and later embed a specific tracker URL and integrity hash, including debug and replay scripts. Leave scriptUrl unset to use these pins. Unexpected CDN changes are blocked without falling back to an unversioned URL. Upgrade the SDK to receive future tracker updates.

Custom script URLs retain self-hosting support. Supply scriptIntegrity to verify custom tracker bytes; a custom URL without a hash opts out of integrity verification.

Tracking features

Prop	Type	Default	Description
`trackWebVitals`	`boolean`	`false`	FCP, LCP, INP, CLS, TTFB, and FPS
`trackErrors`	`boolean`	`false`	JavaScript errors
`trackOutgoingLinks`	`boolean`	`false`	External link clicks
`trackInteractions`	`boolean`	`true`	Rage clicks, dead clicks, and abandoned forms
`trackAttributes`	`boolean`	`false`	Elements with `data-track` attributes
`trackHashChanges`	`boolean`	`false`	URL hash changes

Use trackWebVitals in React, Vue, and Nuxt, or data-track-web-vitals with the CDN script.

Batching and performance

Prop	Type	Default	Description
`enableBatching`	`boolean`	`true`	Compatibility option; browser pageviews still use the batch queue
`batchSize`	`number`	`10`	Events per batch (1-50)
`batchTimeout`	`number`	`5000`	Batch timeout in ms
`enableRetries`	`boolean`	`true`	Retry failed requests
`maxRetries`	`number`	`3`	Maximum retry attempts
`initialRetryDelay`	`number`	`500`	Initial retry delay in ms
`samplingRate`	`number`	`1.0`	Event sampling rate (0.0-1.0)

When verifying browser pageviews, allow for the configured batchTimeout and retry behavior before declaring an event missing. Setting enableBatching=false does not bypass the pageview queue in the current browser tracker. Inspect actual requests and use an explicit batchTimeout when a test needs a shorter queue window; a sent request still does not establish hosted report visibility.

Privacy

Prop	Type	Description
`skipPatterns`	`string[]`	Paths to skip tracking entirely
`maskPatterns`	`string[]`	Paths to mask in analytics

Session replay

Prop	Type	Description
`replay`	`boolean \| { maskText?: boolean; recordIframes?: boolean; scriptUrl?: string; integrity?: string }`	Load the session replay recorder.

Vue

<script setup>
import { Databuddy } from "@databuddy/sdk/vue";
</script>

<template>
<Databuddy
  :client-id="clientId"
  :track-web-vitals="true"
  :track-errors="true"
  :enable-batching="true"
  :batch-size="20"
  :disabled="isDevelopment"
/>
</template>

Vue uses the same props as React but with kebab-case naming:

clientId → :client-id
trackWebVitals → :track-web-vitals
enableBatching → :enable-batching

Vanilla JavaScript

<script
src="https://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id"
data-track-web-vitals
data-track-errors
data-track-outgoing-links
data-enable-batching
data-batch-size="20"
data-batch-timeout="5000"
data-sampling-rate="1.0"
data-skip-patterns='["/admin/**"]'
data-mask-patterns='["/users/*"]'
async
></script>

Data attributes reference

Attribute	Type	Default	Description
`data-client-id`	`string`	Required	Your Client ID
`data-track-web-vitals`	flag	`false`	FCP, LCP, INP, CLS, TTFB, and FPS
`data-track-errors`	flag	`false`	Track JavaScript errors
`data-track-outgoing-links`	flag	`false`	Track external links
`data-track-interactions`	flag	`true`	Rage clicks, dead clicks, and abandoned forms; set `"false"` to turn off
`data-track-attributes`	flag	`false`	Track data-track elements
`data-track-hash-changes`	flag	`false`	Track hash changes
`data-enable-batching`	flag	`true`	Enable event batching
`data-batch-size`	`number`	`10`	Batch size
`data-batch-timeout`	`number`	`5000`	Batch timeout (ms)
`data-sampling-rate`	`number`	`1.0`	Sampling rate
`data-skip-patterns`	`JSON`	`[]`	Paths to skip
`data-mask-patterns`	`JSON`	`[]`	Paths to mask
`data-disabled`	flag	`false`	Disable tracking

Boolean options: Vue templates use kebab-case props such as track-web-vitals; vanilla CDN installs use data-* attributes such as data-track-web-vitals.

Node.js

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

const client = new Databuddy({
// Required
apiKey: process.env.DATABUDDY_API_KEY!,

// Optional: Scope events to a specific website
websiteId: process.env.DATABUDDY_WEBSITE_ID,

// Optional: Logical grouping (e.g. 'auth', 'api', 'jobs')
namespace: "api",

// Optional: Source identifier (e.g. 'backend', 'webhook', 'cli')
source: "backend",

// API
apiUrl: "https://basket.databuddy.cc",

// Batching
enableBatching: true,       // default: true
batchSize: 10,              // max: 100
batchTimeout: 2000,         // ms
maxQueueSize: 1000,

// Deduplication
enableDeduplication: true,  // default: true
maxDeduplicationCacheSize: 10_000,

// Middleware
middleware: [
  (event) => {
    event.properties = { ...event.properties, server: true };
    return event;
  }
],

// Logging
debug: false,
logger: customLogger
});

Node.js options reference

Option	Type	Default	Description
`apiKey`	`string`	Required	Your API key for authentication
`websiteId`	`string`	-	Optional default Client ID to scope events
`namespace`	`string`	-	Optional default namespace for logical grouping
`source`	`string`	-	Optional default source identifier for events
`apiUrl`	`string`	`https://basket.databuddy.cc`	API endpoint
`enableBatching`	`boolean`	`true`	Enable event batching
`batchSize`	`number`	`10`	Batch size (max 100)
`batchTimeout`	`number`	`2000`	Batch timeout in ms
`maxQueueSize`	`number`	`1000`	Maximum queue size
`enableDeduplication`	`boolean`	`true`	Deduplicate events by ID
`maxDeduplicationCacheSize`	`number`	`10000`	Dedup cache size
`middleware`	`Middleware[]`	`[]`	Event transform functions
`debug`	`boolean`	`false`	Enable debug logging
`logger`	`Logger`	-	Custom logger instance

Feature flags (client)

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

<FlagsProvider
clientId="your-client-id"
apiUrl="https://api.databuddy.cc"
user={{
  userId: "user-123",
  email: "user@example.com",
  organizationId: "org-456",
  teamId: "team-789",
  properties: {
    plan: "premium",
    role: "admin"
  }
}}
isPending={isLoadingSession}
disabled={false}
skipStorage={false}
autoFetch={true}
environment="production"
cacheTtl={60_000}
staleTime={30_000}
maxCacheSize={5000}
>
<App />
</FlagsProvider>

Feature flags options reference

Option	Type	Default	Description
`clientId`	`string`	Required	Your Client ID
`apiUrl`	`string`	`https://api.databuddy.cc`	API endpoint
`user`	`UserContext`	-	User context for targeting
`isPending`	`boolean`	`false`	Defer evaluation
`disabled`	`boolean`	`false`	Disable flag evaluation
`skipStorage`	`boolean`	`false`	Skip localStorage caching
`autoFetch`	`boolean`	`true`	Auto-fetch on mount
`environment`	`string`	-	Environment name
`cacheTtl`	`number`	`60000`	Cache TTL (ms)
`staleTime`	`number`	`30000`	Revalidate after (ms)
`maxCacheSize`	`number`	`5000`	Maximum cached entries for other contexts; the configured context keeps every returned flag

User context

Option	Type	Description
`userId`	`string`	Unique user identifier
`email`	`string`	User email
`organizationId`	`string`	Organization ID for group rollouts
`teamId`	`string`	Team ID for group rollouts
`properties`	`object`	Custom targeting properties

Feature flags (server)

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

const flags = createServerFlagsManager({
clientId: process.env.DATABUDDY_CLIENT_ID!,
apiUrl: "https://api.databuddy.cc",
user: {
  userId: "user-123"
},
environment: "production",
cacheTtl: 60_000,
staleTime: 30_000,
maxCacheSize: 5000,
autoFetch: false,
disabled: false
});

Server flags use the same options as client flags, but skipStorage is always true, autoFetch defaults to false, and maxCacheSize caps the entries kept for per-call users.

Environment variables

The browser SDK auto-detects the Client ID from NEXT_PUBLIC_DATABUDDY_CLIENT_ID, NUXT_PUBLIC_DATABUDDY_CLIENT_ID, VITE_DATABUDDY_CLIENT_ID, or REACT_APP_DATABUDDY_CLIENT_ID. Other variables must be wired in explicitly.

Next.js

NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id
DATABUDDY_API_KEY=your-api-key

Vue / Vite

VITE_DATABUDDY_CLIENT_ID=your-client-id

Node.js / server

The Node client does not read environment variables on its own. Pass them through the constructor:

DATABUDDY_API_KEY=your-api-key
DATABUDDY_WEBSITE_ID=your-client-id  # Optional default Client ID
DATABUDDY_API_URL=https://basket.databuddy.cc  # Optional

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

const client = new Databuddy({
apiKey: process.env.DATABUDDY_API_KEY!,
websiteId: process.env.DATABUDDY_WEBSITE_ID,
apiUrl: process.env.DATABUDDY_API_URL
});

The cookieless analytics overview explains the collection choices behind these options. Before enabling diagnostics, review the privacy considerations in error tracking and check the actual payloads your application produces.

React SDK

React/Next.js integration

Node SDK

Server-side tracking

Feature flags

Client-side feature flags

Configuration reference