# Configuration Reference

> Complete configuration options for all Databuddy SDK platforms


import { Callout, CodeBlock, Card, Cards } from "@/components/docs";

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

## React / Next.js

<CodeBlock language="tsx">
  {`import { Databuddy } from "@databuddy/sdk/react";

<Databuddy
  // Required
  clientId="your-client-id"
  
  // API endpoints
  apiUrl="https://basket.databuddy.cc"
  scriptUrl="https://cdn.databuddy.cc/databuddy.js"
  
  // Core tracking
  trackWebVitals={true}   // opt in; default: false
  trackErrors             // default: false
  trackOutgoingLinks      // default: false
  trackInteractions       // default: false
  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}
/>`}
</CodeBlock>

### 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` | API endpoint |
| `scriptUrl` | `string` | `https://cdn.databuddy.cc/databuddy.js` | Script URL |
| `disabled` | `boolean` | `false` | Disable all tracking |
| `debug` | `boolean` | `false` | Enable debug logging |

#### 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` | `false` | Button clicks and form submissions |
| `trackAttributes` | `boolean` | `false` | Elements with `data-track` attributes |
| `trackHashChanges` | `boolean` | `false` | URL hash changes |

<Callout type="info">
  Use `trackWebVitals` in React, Vue, and Nuxt, or `data-track-web-vitals` with the CDN script.
</Callout>

#### Batching & Performance

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `enableBatching` | `boolean` | `true` | Group events into batches |
| `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) |

#### Privacy

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

## Vue

<CodeBlock language="html">
  {`<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>`}
</CodeBlock>

Vue uses the same props as React but with kebab-case naming:
- `clientId` → `:client-id`
- `trackWebVitals` → `:track-web-vitals`
- `enableBatching` → `:enable-batching`

## Vanilla JavaScript

<CodeBlock language="html">
  {`<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>`}
</CodeBlock>

### 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 | `false` | Track interactions |
| `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 |

<Callout type="info">
  **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`.
</Callout>

## Node.js

<CodeBlock language="tsx">
  {`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
});`}
</CodeBlock>

### 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)

<CodeBlock language="tsx">
  {`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}
  debug={false}
  skipStorage={false}
  autoFetch={true}
  environment="production"
  cacheTtl={60_000}
  staleTime={30_000}
  maxCacheSize={5000}
>
  <App />
</FlagsProvider>`}
</CodeBlock>

### 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 |
| `debug` | `boolean` | `false` | Enable debug logging |
| `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 in-memory cache entries |

### 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)

<CodeBlock language="tsx">
  {`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,
  debug: false,
  disabled: false
});`}
</CodeBlock>

Server flags use the same options as client flags, but `skipStorage` is always `true`, `autoFetch` defaults to `false`, and the in-memory cache is capped by `maxCacheSize`.

## 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

<CodeBlock language="bash" filename=".env.local">
  {`NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id
DATABUDDY_API_KEY=your-api-key`}
</CodeBlock>

### Vue / Vite

<CodeBlock language="bash" filename=".env">
  {`VITE_DATABUDDY_CLIENT_ID=your-client-id`}
</CodeBlock>

### Node.js / Server

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

<CodeBlock language="bash" filename=".env">
  {`DATABUDDY_API_KEY=your-api-key
DATABUDDY_WEBSITE_ID=your-client-id  # Optional default Client ID
DATABUDDY_API_URL=https://basket.databuddy.cc  # Optional`}
</CodeBlock>

<CodeBlock language="tsx">
  {`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
});`}
</CodeBlock>

## Related

<Cards>
  <Card title="React SDK" href="/docs/sdk/react">
    React/Next.js integration
  </Card>
  <Card title="Node SDK" href="/docs/sdk/node">
    Server-side tracking
  </Card>
  <Card title="Feature Flags" href="/docs/sdk/feature-flags">
    Client-side feature flags
  </Card>
</Cards>