Configuration Reference

Every option you can set when initializing the SDK. Most of the defaults are sensible, so you probably don't need to touch most of these.

AnalyticsConfig

The main configuration object.

interface AnalyticsConfig {
  apiKey: string;
  host?: string;
  flushAt?: number;
  flushInterval?: number;
  sessionTimeout?: number;
  cookieDomain?: string;
  debug?: boolean;
  respectDNT?: boolean;
  maxRetries?: number;
  errors?: ErrorCaptureConfig;
}

Properties

Prop

Type

ErrorCaptureConfig

Configuration for the error tracking feature.

interface ErrorCaptureConfig {
  enabled?: boolean;
  captureConsoleErrors?: boolean;
  captureNetworkErrors?: boolean;
  maxBreadcrumbs?: number;
  beforeSend?: (payload: ErrorPayload) => ErrorPayload | null;
}

Properties

Prop

Type

beforeSend Examples

Filter out the noise:

{
  errors: {
    enabled: true,
    beforeSend: (payload) => {
      // ResizeObserver errors are annoying and usually harmless
      if (payload.message.includes('ResizeObserver')) {
        return null;
      }

      // Browser extension errors aren't your problem
      if (payload.stack?.includes('chrome-extension://')) {
        return null;
      }

      return payload;
    },
  },
}

Add build context:

{
  errors: {
    enabled: true,
    beforeSend: (payload) => {
      payload.context = {
        ...payload.context,
        release: process.env.NEXT_PUBLIC_VERSION,
        buildId: process.env.NEXT_PUBLIC_BUILD_ID,
      };
      return payload;
    },
  },
}

Scrub sensitive data:

{
  errors: {
    enabled: true,
    beforeSend: (payload) => {
      // Remove email addresses from error messages
      payload.message = payload.message.replace(
        /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
        '[EMAIL_REDACTED]'
      );
      return payload;
    },
  },
}

Default Values

For reference, here's what you get out of the box:

const DEFAULT_CONFIG = {
  host: 'https://thisbefine.com',
  flushAt: 20,
  flushInterval: 10000,       // 10 seconds
  sessionTimeout: 1800000,    // 30 minutes
  debug: false,
  respectDNT: true,
  maxRetries: 3,
};

These are pretty sensible defaults. You probably don't need to change them.

Configuration Recipes

The "Just Ship It" Config

{
  apiKey: process.env.NEXT_PUBLIC_THISBEFINE_API_KEY!,
}

That's it. Everything else is optional.

The "I'm Debugging" Config

{
  apiKey: process.env.NEXT_PUBLIC_THISBEFINE_API_KEY!,
  debug: true,
  flushAt: 1,          // Send immediately
  flushInterval: 1000, // Check every second
}

The "Full Production" Config

{
  apiKey: process.env.NEXT_PUBLIC_THISBEFINE_API_KEY!,
  flushAt: 20,
  flushInterval: 10000,
  sessionTimeout: 1800000,
  respectDNT: true,
  maxRetries: 3,
  errors: {
    enabled: true,
    captureConsoleErrors: false,
    captureNetworkErrors: true,
    maxBreadcrumbs: 50,
    beforeSend: (payload) => {
      // Filter browser extension errors
      if (payload.stack?.includes('chrome-extension://')) {
        return null;
      }
      // Add release info
      payload.context = {
        ...payload.context,
        release: process.env.NEXT_PUBLIC_VERSION,
      };
      return payload;
    },
  },
}

The "Cross-Subdomain" Config

Tracking across app.example.com and www.example.com:

{
  apiKey: 'tif_xxx',
  cookieDomain: '.example.com',
}

The "Self-Hosted" Config

Running your own Thisbefine instance:

{
  apiKey: 'tif_xxx',
  host: 'https://analytics.yourcompany.com',
}

The "Long Sessions" Config

For apps where users stay active for hours (like dashboards or dev tools):

{
  apiKey: 'tif_xxx',
  sessionTimeout: 7200000, // 2 hours
}

Environment Variables

Here's the recommended setup:

.env.local

# Required
NEXT_PUBLIC_THISBEFINE_API_KEY=tif_your_api_key

# Optional (for build context)
NEXT_PUBLIC_VERSION=1.0.0
NEXT_PUBLIC_BUILD_ID=abc123

The NEXT_PUBLIC_ prefix is required for Next.js to expose these to the browser. Without it, they're server-only.

TypeScript

Import the types for full type safety:

import type { AnalyticsConfig, ErrorCaptureConfig } from '@thisbefine/analytics';

const config: AnalyticsConfig = {
  apiKey: 'tif_xxx',
  errors: {
    enabled: true,
  } satisfies ErrorCaptureConfig,
};

Your editor will autocomplete everything. Typos become compile errors. This is fine. 🔥

Configuration

On this page