Databuddy is a privacy-first web and product analytics platform that operates without cookies, fingerprinting, or persistent identifiers. Built with Next.js and Tailwind CSS on the frontend, powered by Elysia and tRPC for the API layer, it uses Neon Postgres for metadata and ClickHouse for high-performance analytics queries. The platform provides accurate website and product analytics while respecting user privacy by design.

This guide covers everything you need to deploy Databuddy, integrate it into your website, and start collecting actionable analytics data without consent banners or compliance concerns.

Why Databuddy?

Traditional analytics platforms like Google Analytics face increasing challenges: declining data accuracy due to consent rejection, cookie blockers, and stricter privacy regulations. Databuddy solves these problems by never requiring cookies or personal data collection in the first place.

Key Benefits

  • Zero consent friction: No cookie banners needed since no personal data is collected
  • 100% data capture: Track all visitors, not just those who accept cookies (typically 50-70%)
  • Minimal footprint: ~3KB script size (247x smaller than Google Analytics), negligible impact on Core Web Vitals
  • GDPR/CCPA compliant by design: No personal data processing means no consent requirements
  • Full data ownership: Self-host or use managed service with complete control over your data
  • Open source: Licensed under AGPL-3.0; inspect the code, contribute, and customize to your needs
  • All-in-one platform: Analytics, feature flags, error tracking, and Web Vitals monitoring in a single tool
  • Eco-friendly: Up to 10x more energy-efficient than traditional analytics solutions

Deployment Options

Databuddy can be deployed in several ways depending on your infrastructure preferences and scale requirements.

Option 1: Managed Cloud (Quickest Start)

The fastest way to get started is using Databuddy's managed cloud service at databuddy.cc. Sign up, add your domain, and embed the tracking script.

<!-- Add to your HTML head section -->
<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="YOUR_CLIENT_ID"
  async>
</script>

The managed service includes:

  • Free tier with up to 10,000 monthly events
  • Real-time analytics dashboard
  • Automatic updates and maintenance
  • CDN-delivered tracking script
  • Feature flags with millisecond global deployments
  • Error tracking and Web Vitals monitoring

Option 2: Self-Hosted

For organizations requiring complete data control, self-hosting is available. Databuddy uses Bun as its runtime and requires both Postgres (or Neon) and ClickHouse for optimal performance.

Prerequisites

  • Bun 1.3.4+ or Node.js 20+
  • Docker and Docker Compose (for containerized deployment)
  • Postgres database (or Neon Postgres for serverless)
  • ClickHouse instance for analytics data
  • Minimum 2GB RAM (4GB recommended)
  • Domain name with SSL certificate

Environment Configuration

# .env configuration
DATABASE_URL="postgres://databuddy:password@localhost:5432/databuddy"
CLICKHOUSE_URL="http://default:@localhost:8123/databuddy_analytics"
SECRET_KEY=$(openssl rand -hex 32)

Docker Compose Setup

Clone the repository and use the provided docker-compose.yaml:

# Clone the repository
git clone https://github.com/databuddy-analytics/Databuddy.git
cd Databuddy

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start all services
docker compose up -d

# Check logs
docker compose logs -f

For detailed self-hosting instructions, refer to the official documentation at databuddy.cc/docs.

Integration Guide

Once Databuddy is running, integrate the tracking script into your website or application.

Basic HTML Integration

<!DOCTYPE html>
<html>
<head>
  <!-- Add Databuddy tracking script -->
  <script
    src="https://cdn.databuddy.cc/databuddy.js"
    data-client-id="YOUR_CLIENT_ID"
    data-track-screen-views="true"
    data-track-attributes="true"
    data-track-errors="true"
    async>
  </script>
</head>
<body>
  <!-- Your content -->
</body>
</html>

Next.js Integration (App Router)

// app/layout.tsx
import { Databuddy } from '@databuddy/sdk/react';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Databuddy
          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
          trackScreenViews={true}
          trackPerformance
          trackWebVitals={true}
          trackErrors={true}
        />
        {children}
      </body>
    </html>
  );
}

Next.js Integration (Pages Router)

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { Databuddy } from '@databuddy/sdk/react';
import { useRouter } from 'next/router';
import { useEffect } from 'react';
import { track } from '@databuddy/sdk';

function MyApp({ Component, pageProps }: AppProps) {
  const router = useRouter();

  useEffect(() => {
    const handleRouteChange = (url: string) => {
      track('screen_view', {
        screen_name: url,
        screen_class: 'Next.js'
      });
    };

    router.events.on('routeChangeComplete', handleRouteChange);
    return () => {
      router.events.off('routeChangeComplete', handleRouteChange);
    };
  }, [router.events]);

  return (
    <>
      <Databuddy
        clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
        trackScreenViews={true}
        trackAttributes={true}
      />
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

React SPA Integration

# Install the SDK
bun add @databuddy/sdk
# or
npm install @databuddy/sdk
// App.tsx
import { Databuddy } from '@databuddy/sdk/react';

function App() {
  return (
    <>
      <Databuddy
        clientId="YOUR_CLIENT_ID"
        trackScreenViews
        trackHashChanges
        trackAttributes
      />
      {/* Your app components */}
    </>
  );
}

WordPress Integration

Add the script using a plugin like "Insert Headers and Footers" or directly in your theme:

<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="YOUR_CLIENT_ID"
  data-track-screen-views="true"
  data-track-attributes="true"
  data-track-outgoing-links="true"
  async>
</script>

Shopify Integration

Add to your theme.liquid file before the closing </head> tag:

<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="YOUR_CLIENT_ID"
  data-track-screen-views="true"
  data-track-attributes="true"
  data-track-outgoing-links="true"
  async>
</script>

Custom Event Tracking

Beyond automatic pageview tracking, Databuddy supports custom events for tracking specific user actions.

Basic Event Tracking

import { track } from '@databuddy/sdk';

// Track a custom event
track('signup_clicked', {
  plan: 'pro',
  source: 'pricing_page'
});

// Track form submissions
document.querySelector('#contact-form').addEventListener('submit', (e) => {
  track('form_submit', {
    form_name: 'contact',
    has_message: e.target.message.value.length > 0
  });
});

// Track button clicks
document.querySelector('.cta-button').addEventListener('click', () => {
  track('cta_click', {
    button_text: 'Get Started',
    page: window.location.pathname
  });
});

E-commerce Event Tracking

import { track } from '@databuddy/sdk';

// Track product views
track('product_view', {
  product_id: 'SKU123',
  product_name: 'Premium Widget',
  category: 'widgets',
  price: 99.99,
  currency: 'USD'
});

// Track add to cart
track('add_to_cart', {
  product_id: 'SKU123',
  quantity: 2,
  cart_value: 199.98
});

// Track purchases (aggregated, no PII)
track('purchase_completed', {
  order_value: 199.98,
  item_count: 2,
  payment_method: 'card',
  currency: 'USD'
});

Conversion Funnel Tracking

import { track } from '@databuddy/sdk';

// Track funnel steps
const trackFunnelStep = (step, data = {}) => {
  track('funnel_step', {
    funnel_name: 'onboarding',
    step_number: step,
    step_name: data.name,
    ...data
  });
};

// Usage
trackFunnelStep(1, { name: 'signup_started' });
trackFunnelStep(2, { name: 'email_verified' });
trackFunnelStep(3, { name: 'profile_completed' });
trackFunnelStep(4, { name: 'first_action' });

Feature Flags

Databuddy includes built-in feature flags, eliminating the need for a separate service.

import { useFlags } from '@databuddy/sdk/react';

function MyComponent() {
  const { isEnabled } = useFlags();
  const newDashboard = isEnabled('new-dashboard');

  return (
    <div>
      {newDashboard.isReady && newDashboard.enabled && (
        <NewDashboard />
      )}
    </div>
  );
}

Error Tracking

Automatically capture and track errors in your application:

import { trackError } from '@databuddy/sdk';

// Automatic error tracking is enabled with trackErrors={true}
// Manual error tracking:
trackError('API request failed', {
  endpoint: '/api/products',
  error_type: 'network_error'
});

Dashboard and Reporting

Databuddy provides a real-time analytics dashboard with key metrics and visualizations.

Available Metrics

  • Visitors: Unique and total visitor counts (session-based, not user-based)
  • Page Views: Total pages viewed with path-level breakdown
  • Bounce Rate: Single-page session percentage
  • Session Duration: Average time spent on site
  • Traffic Sources: Referrer breakdown without personal tracking
  • Geography: Country/region based on anonymized IP geolocation
  • Devices: Browser and device type distribution
  • Custom Events: All tracked events with property breakdowns
  • Feature Flags: Usage and adoption metrics
  • Errors: Error tracking with context

Web Vitals Monitoring

Databuddy automatically tracks Core Web Vitals for performance monitoring:

  • LCP (Largest Contentful Paint): Loading performance
  • FID (First Input Delay): Interactivity responsiveness
  • CLS (Cumulative Layout Shift): Visual stability
  • TTFB (Time to First Byte): Server response time
  • FCP (First Contentful Paint): Initial render time

API Access

Access your analytics data programmatically through the Databuddy API.

Authentication

# Generate an API key in the dashboard settings
export DATABUDDY_API_KEY="your-api-key"

# All API requests require the key in headers
curl -H "Authorization: Bearer $DATABUDDY_API_KEY" \
  https://basket.databuddy.cc/api/v1/stats

Fetching Statistics

// Fetch visitor stats for the last 30 days
const response = await fetch('https://basket.databuddy.cc/api/v1/stats', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  method: 'POST',
  body: JSON.stringify({
    site_id: 'your-site-id',
    period: '30d',
    metrics: ['visitors', 'pageviews', 'bounce_rate'],
    dimensions: ['page', 'source']
  })
});

const data = await response.json();
console.log(data);

Privacy Architecture

Understanding how Databuddy achieves privacy-first analytics helps ensure proper deployment.

What Databuddy Does NOT Collect

  • IP addresses (immediately anonymized, never stored in original form)
  • User identifiers or cookies
  • Device fingerprints
  • Cross-site tracking data
  • Personal information of any kind
  • Names, email addresses, or any PII from website visitors

What Databuddy DOES Collect

  • Page URL and referrer
  • Viewport dimensions and device type
  • Browser and OS (from user agent, aggregated)
  • Country/region (from anonymized IP geolocation)
  • Session-level engagement metrics
  • Custom events you explicitly track
  • Web Vitals performance data

Session Management Without Cookies

Databuddy uses a combination of non-identifying signals to detect sessions without persistent storage. The session hash changes daily and cannot identify returning users across days or sessions—it only groups pageviews within a single visit.

Key privacy principles:

  • All data is aggregated and anonymized
  • No cross-site tracking capability
  • No user profiles are built
  • Data is never sold or shared with third parties
  • GDPR legal basis: Legitimate interests (no consent required)

Script Configuration Options

Customize tracking behavior using data attributes:

<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="YOUR_CLIENT_ID"
  data-track-screen-views="true"
  data-track-attributes="true"
  data-track-outgoing-links="true"
  data-track-interactions="true"
  data-track-performance="true"
  data-track-web-vitals="true"
  data-track-errors="true"
  data-track-scroll-depth="true"
  data-track-hash-changes="true"
  data-debug="false"
  async>
</script>

Troubleshooting

Script Not Loading

  • Check browser console for errors
  • Verify the data-client-id matches your configured site ID
  • Ensure the script URL is correct and accessible
  • Check for ad blockers (some may block analytics scripts)
  • Clear browser cache and test in incognito mode

Events Not Appearing

  • Verify window.databuddy is defined before tracking
  • Ensure event names follow the naming convention (snake_case preferred)
  • Check the dashboard—events appear in real-time
  • Enable debug mode with data-debug="true" for console logging

React/Next.js Issues

  • Ensure the SDK is installed: bun add @databuddy/sdk
  • Verify environment variable is set: NEXT_PUBLIC_DATABUDDY_CLIENT_ID
  • Check that the Databuddy component is rendered in your layout

Resources and Support

Databuddy provides a modern approach to web analytics that prioritizes both privacy and accuracy. By eliminating cookies and personal data collection, you gain 100% visitor visibility while maintaining full regulatory compliance. Start with the managed service for quick deployment, or explore self-hosting for complete data sovereignty.