DataFast NPM SDK

Install DataFast as an npm package for type-safe analytics tracking in JavaScript and TypeScript applications. Perfect for React, Next.js, Vue, Angular, and other web frameworks.

Why use the SDK?

TypeScript support - Full type definitions for autocomplete and type safety
Tree-shakeable - Only import what you need
Framework agnostic - Works with React, Vue, Angular, Svelte, and vanilla JS
Automatic tracking - Built-in page view, session, and device tracking
Offline-ready - Queues events when offline and syncs when back online

Installation

npm install datafast

Quick Start

Basic setup

import { initDataFast } from 'datafast';

// Initialize the SDK
const datafast = await initDataFast({
  websiteId: 'dfid_your_website_id',
  domain: 'yourdomain.com', // optional, defaults to current hostname
});

// Track page views
datafast.trackPageview();

// Track custom events
datafast.track('button_click', { button: 'signup' });

// Identify users
datafast.identify('user_123', { 
  email: 'user@example.com',
  plan: 'pro' 
});

React / Next.js example

// lib/analytics.ts
import { initDataFast } from 'datafast';

let datafast: any = null;

export async function getAnalytics() {
  if (!datafast) {
    datafast = await initDataFast({
      websiteId: process.env.NEXT_PUBLIC_DATAFAST_WEBSITE_ID!,
      domain: process.env.NEXT_PUBLIC_DATAFAST_DOMAIN,
    });
  }
  return datafast;
}

Then use it in your app:

// app/page.tsx or components/SignupButton.tsx
import { getAnalytics } from '@/lib/analytics';

export default function SignupButton() {
  const handleSignup = async () => {
    const analytics = await getAnalytics();
    
    // Track the signup event
    analytics.track('signup', {
      plan: 'free',
      source: 'homepage'
    });
  };

  return <button onClick={handleSignup}>Sign Up</button>;
}

Automatic page view tracking in Next.js

Track page views automatically on route changes:

// app/layout.tsx or pages/_app.tsx
'use client';

import { useEffect } from 'react';
import { usePathname } from 'next/navigation';
import { getAnalytics } from '@/lib/analytics';

export default function RootLayout({ children }) {
  const pathname = usePathname();

  useEffect(() => {
    (async () => {
      const analytics = await getAnalytics();
      analytics.trackPageview();
    })();
  }, [pathname]);

  return <html><body>{children}</body></html>;
}

Configuration Options

interface DataFastWebConfig {
  websiteId: string;        // Required: Your DataFast website ID
  domain?: string;          // Optional: Domain (defaults to current hostname)
  apiUrl?: string;          // Optional: Custom API endpoint
  debug?: boolean;          // Optional: Enable debug logging
  flushInterval?: number;   // Optional: Flush interval in ms (default: 5000)
  maxQueueSize?: number;    // Optional: Max queue size before flush (default: 10)
}

API Methods

Track custom events

// Simple event
datafast.track('button_click');

// Event with custom data
datafast.track('purchase', {
  amount: 99.99,
  currency: 'USD',
  product: 'Premium Plan'
});

Track page views

// Track current page
datafast.trackPageview();

// Track specific URL
datafast.trackPageview('/custom/path');

// Track with custom data
datafast.trackPageview('/pricing', {
  experiment: 'pricing-test-v2'
});

Identify users

// Simple identification
datafast.identify('user_123');

// With user properties
datafast.identify('user_123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
  signup_date: '2024-01-15'
});

Flush events manually

By default, events are queued and sent automatically. You can manually flush:

// Force send all queued events immediately
await datafast.flush();

Reset the client

Clear visitor ID and session (useful for logout):

datafast.reset();

Advanced Usage

Custom storage adapter (web)

import { createDataFastClient, createMemoryStorageAdapter } from 'datafast';

// Use in-memory storage (no persistence)
const datafast = await createDataFastClient({
  websiteId: 'dfid_your_id',
  storage: createMemoryStorageAdapter(),
  // ... other config
});

Server-side tracking (Node.js)

import { createDataFastClient } from '@datafast/core';

const datafast = await createDataFastClient({
  websiteId: 'dfid_your_id',
  domain: 'yourdomain.com',
  // Provide custom storage and network adapters for Node.js
});

Access the singleton client

After initialization, you can access the client anywhere:

import { getDataFastClient } from 'datafast';

const datafast = getDataFastClient();
datafast.track('event_name');

Package Structure

datafast - Main SDK for web applications

Entry point: datafast or datafast/web
Includes localStorage, fetch adapters
Auto-detects device, viewport, referrer

@datafast/core - Core tracking logic (universal)

No platform-specific code
Use for custom integrations
Requires you to provide storage/network adapters

@datafast/web - Web-specific implementation

Same as main datafast package
Use if you prefer explicit imports

TypeScript Support

All packages include full TypeScript definitions:

import type { 
  DataFastClient, 
  DataFastConfig,
  TrackEventData 
} from 'datafast';

const config: DataFastConfig = {
  websiteId: 'dfid_123',
  debug: true
};

Troubleshooting

Events not showing up?

Check your websiteId is correct
Enable debug: true to see console logs
Verify your domain matches your DataFast dashboard settings
Check network requests in browser DevTools

TypeScript errors?

Ensure you're using TypeScript 5.0+
Run npm install @types/node if needed

Need help? Email us at marc@datafa.st

Something missing? Suggest features ✍️