clickchutney-react

v1.4.0

Published

a year ago

React/Next.js analytics provider for ClickChutney

0High
0Medium
0Low

contactsushil

analytics react nextjs tracking clickchutney

ClickChutney React

Official React/Next.js SDK for ClickChutney Analytics - as vibrant and accessible as Indian street food! 🍛

Features

✨ Zero Dependencies - Lightweight and fast
📊 Auto Tracking - Pageviews, clicks, forms, and errors
⚡ React 19 Ready - Full compatibility with latest React
🔄 SPA Support - Next.js App Router and client navigation
🎯 TypeScript First - Complete type safety
📱 Cross-Platform - Web, mobile, and server-side rendering
🛡️ Privacy Focused - GDPR compliant with anonymization options
⚙️ Highly Configurable - 20+ configuration options

Compatibility

| Framework | Versions | Status | |-----------|----------|---------| | React | ≥16.8.0, 17.x, 18.x, 19.x | ✅ Fully Supported | | Next.js | ≥13.0.0 (App Router & Pages) | ✅ Fully Supported | | Vite | All versions | ✅ Fully Supported | | Create React App | All versions | ✅ Fully Supported | | Remix | v1.x, v2.x | ✅ Fully Supported | | Gatsby | v4.x, v5.x | ✅ Fully Supported |

React Version Support

React 16.8+: Hooks support (useState, useEffect)
React 17: Full compatibility
React 18: Concurrent features supported
React 19: Latest features supported

Next.js Version Support

Next.js 13+: App Router, Pages Router, SSR, SSG
Next.js 14+: Turbopack, Server Components
Next.js 15+: Full compatibility

Installation

npm install clickchutney-react
# or
yarn add clickchutney-react
# or
pnpm add clickchutney-react

Quick Start

1. Wrap your app with the provider

Next.js App Router (app/layout.tsx)

Step 1: Create a client component wrapper:

// components/AnalyticsProvider.tsx
'use client';

import { ClickChutneyProvider } from 'clickchutney-react';

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
  return (
    <ClickChutneyProvider
      config={{
        trackingId: "your-tracking-id",
        debug: process.env.NODE_ENV === 'development'
      }}
    >
      {children}
    </ClickChutneyProvider>
  );
}

Step 2: Use in your layout:

// app/layout.tsx
import { AnalyticsProvider } from '@/components/AnalyticsProvider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <AnalyticsProvider>
          {children}
        </AnalyticsProvider>
      </body>
    </html>
  );
}

Next.js Pages Router (_app.tsx)

import type { AppProps } from 'next/app';
import { ClickChutneyProvider } from 'clickchutney-react';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <ClickChutneyProvider
      config={{
        trackingId: "your-tracking-id",
        debug: process.env.NODE_ENV === 'development'
      }}
    >
      <Component {...pageProps} />
    </ClickChutneyProvider>
  );
}

Vite/Create React App

// src/main.tsx or src/App.tsx
import { ClickChutneyProvider } from 'clickchutney-react';

function App() {
  return (
    <ClickChutneyProvider
      config={{
        trackingId: "your-tracking-id",
        autoPageview: true
      }}
    >
      <YourApp />
    </ClickChutneyProvider>
  );
}

Usage

Manual Event Tracking

import { track, pageview, identify } from 'clickchutney-react';

// Track custom events
track('button_click', { 
  button_name: 'header_cta',
  campaign: 'summer_sale' 
});

// Track pageviews manually
pageview('/custom-page', { 
  title: 'Custom Page',
  category: 'marketing' 
});

// Identify users
identify({
  id: 'user_123',
  email: '[email protected]',
  plan: 'premium'
});

Using Hooks (Optional)

import { useClickChutney, useEventTracking } from 'clickchutney-react';

function MyComponent() {
  const { track, identify, isReady } = useClickChutney();
  const trackEvent = useEventTracking();

  const handleClick = () => {
    track('product_view', { 
      product_id: '12345',
      category: 'electronics' 
    });
  };

  const handlePurchase = () => {
    trackEvent('purchase', {
      value: 99.99,
      currency: 'USD',
      items: ['laptop', 'mouse']
    });
  };

  return (
    <div>
      <button onClick={handleClick}>View Product</button>
      <button onClick={handlePurchase}>Buy Now</button>
      {isReady && <span>Analytics Ready ✅</span>}
    </div>
  );
}

Configuration Options

interface ClickChutneyConfig {
  trackingId: string;              // Required: Your tracking ID
  endpoint?: string;               // Optional: Custom endpoint
  debug?: boolean;                 // Optional: Enable debug logging
  autoPageview?: boolean;          // Optional: Auto-track pageviews (default: true)
  enableHeartbeat?: boolean;       // Optional: Enable heartbeat tracking (default: true)
  heartbeatInterval?: number;      // Optional: Heartbeat interval in ms (default: 30000)
  enableSPATracking?: boolean;     // Optional: Enable SPA route tracking (default: true)
  trackUtmParams?: boolean;        // Optional: Track UTM parameters (default: true)
  trackScrollDepth?: boolean;      // Optional: Track scroll milestones (default: true)
  trackClicks?: boolean;           // Optional: Auto-track clicks (default: true)
  trackForms?: boolean;            // Optional: Auto-track forms (default: true)
  trackErrors?: boolean;           // Optional: Auto-track errors (default: true)
}

Hooks

useClickChutney()

Main hook providing access to all tracking methods.

import { useClickChutney } from 'clickchutney-react';

function MyComponent() {
  const { track, pageview, identify, isReady, error } = useClickChutney();

  if (!isReady) {
    return <div>Loading analytics...</div>;
  }

  return <div>Analytics ready!</div>;
}

useEventTracking()

Hook with utilities for common event types.

import { useEventTracking } from 'clickchutney-react';

function MyComponent() {
  const { 
    track, 
    trackClick, 
    trackFormSubmit, 
    trackPurchase,
    trackSignup,
    trackLogin,
    trackSearch,
    trackDownload,
    trackError 
  } = useEventTracking();

  return (
    <button onClick={() => trackClick('hero_button', { variant: 'primary' })}>
      Track This Click
    </button>
  );
}

usePageTracking()

Hook for automatic page tracking.

import { usePageTracking } from 'clickchutney-react';

function ProductPage({ productId }: { productId: string }) {
  usePageTracking({
    page: `/product/${productId}`,
    title: 'Product Details',
    properties: {
      productId,
      category: 'ecommerce'
    }
  });

  return <div>Product Details</div>;
}

useUserTracking()

Hook for user identification.

import { useUserTracking } from 'clickchutney-react';

function LoginHandler() {
  const { identify } = useUserTracking();

  const handleLogin = (user) => {
    identify(user.id, {
      email: user.email,
      name: user.name,
      plan: user.plan
    });
  };

  return <LoginForm onLogin={handleLogin} />;
}

useFormTracking()

Hook for form tracking.

import { useFormTracking } from 'clickchutney-react';

function ContactForm() {
  const { handleSubmit } = useFormTracking('contact_form', {
    trackSubmit: true,
    properties: { source: 'homepage' }
  });

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" name="email" />
      <button type="submit">Submit</button>
    </form>
  );
}

useSession()

Hook for accessing session data.

import { useSession } from 'clickchutney-react';

function SessionInfo() {
  const session = useSession();

  return (
    <div>
      <p>Session ID: {session?.id}</p>
      <p>Page Views: {session?.pageviews}</p>
      <p>Landing Page: {session?.landingPage}</p>
    </div>
  );
}

Components

ClickTracker

Component for automatic click tracking.

import { ClickTracker } from 'clickchutney-react';

<ClickTracker
  eventName="cta_clicked"
  properties={{ location: 'hero', variant: 'primary' }}
>
  <button>Call to Action</button>
</ClickTracker>

FormTracker

Component for automatic form tracking.

import { FormTracker } from 'clickchutney-react';

<FormTracker
  formName="newsletter_signup"
  trackSubmit={true}
  trackChange={false}
  properties={{ source: 'homepage' }}
>
  <input type="email" />
  <button type="submit">Subscribe</button>
</FormTracker>

Event Examples

E-commerce Tracking

import { useEventTracking, EVENTS } from 'clickchutney-react';

function EcommerceComponent() {
  const { track } = useEventTracking();

  // Product view
  const trackProductView = () => {
    track(EVENTS.PRODUCT_VIEW, {
      productId: 'prod_123',
      productName: 'Awesome Product',
      category: 'electronics',
      price: 299.99
    });
  };

  // Add to cart
  const trackAddToCart = () => {
    track(EVENTS.ADD_TO_CART, {
      productId: 'prod_123',
      quantity: 1,
      value: 299.99
    });
  };

  // Purchase
  const trackPurchase = () => {
    track(EVENTS.PURCHASE, {
      orderId: 'order_456',
      revenue: 299.99,
      currency: 'USD',
      items: ['prod_123']
    });
  };
}

User Lifecycle

import { useEventTracking, useUserTracking } from 'clickchutney-react';

function UserLifecycle() {
  const { trackSignup, trackLogin } = useEventTracking();
  const { identify } = useUserTracking();

  const handleSignup = (user) => {
    trackSignup('email', { plan: 'free' });
    identify(user.id, {
      email: user.email,
      signupDate: new Date().toISOString()
    });
  };

  const handleLogin = (user) => {
    trackLogin('email');
    identify(user.id, { lastLogin: new Date().toISOString() });
  };
}

Advanced Examples

E-commerce Tracking

import { track } from 'clickchutney-react';

// Track purchases
track('purchase', {
  transaction_id: 'txn_123',
  value: 129.99,
  currency: 'USD',
  items: [
    { id: 'prod_1', name: 'Laptop', category: 'Electronics', price: 129.99 }
  ]
});

// Track product views
track('view_item', {
  item_id: 'prod_1',
  item_name: 'Laptop',
  item_category: 'Electronics',
  value: 129.99
});

User Journey Tracking

import { identify, track } from 'clickchutney-react';

// Identify user on login
identify({
  id: 'user_123',
  email: '[email protected]',
  name: 'John Doe',
  plan: 'premium',
  company: 'Acme Corp'
});

// Track key user actions
track('trial_started', { plan: 'premium' });
track('feature_used', { feature: 'dashboard' });
track('support_contacted', { method: 'chat' });

A/B Testing Integration

import { track } from 'clickchutney-react';

function ABTestComponent() {
  const variant = Math.random() > 0.5 ? 'A' : 'B';

  // Track experiment exposure
  track('experiment_viewed', {
    experiment_name: 'homepage_hero',
    variant: variant
  });

  return (
    <div>
      {variant === 'A' ? <HeroA /> : <HeroB />}
    </div>
  );
}

Server-Side Rendering (SSR)

ClickChutney React is SSR-safe and works seamlessly with:

Next.js - Both App Router and Pages Router
Remix - Server and client rendering
Gatsby - Static site generation

The provider automatically detects server vs client environment and only initializes tracking on the client side.

Environment Variables

# Next.js
NEXT_PUBLIC_CLICKCHUTNEY_TRACKING_ID=your-tracking-id
NEXT_PUBLIC_CLICKCHUTNEY_ENDPOINT=https://your-endpoint.com

# Vite
VITE_CLICKCHUTNEY_TRACKING_ID=your-tracking-id
VITE_CLICKCHUTNEY_ENDPOINT=https://your-endpoint.com

TypeScript Support

Full TypeScript support with complete type definitions:

import type { 
  ClickChutneyConfig, 
  TrackingEvent, 
  UserTraits 
} from 'clickchutney-react';

const config: ClickChutneyConfig = {
  trackingId: "your-id",
  debug: true
};

const event: TrackingEvent = {
  product_id: "123",
  category: "electronics",
  value: 99.99
};

const user: UserTraits = {
  id: "user_123",
  email: "[email protected]",
  plan: "premium"
};

Performance

Bundle Size: ~8KB gzipped
Zero Dependencies: No external libraries
Tree Shaking: Import only what you need
Lazy Loading: Scripts load asynchronously
Beacon API: Uses sendBeacon for reliable data transmission

Privacy & GDPR Compliance

<ClickChutneyProvider
  config={{
    trackingId: "your-id",
    anonymizeIp: true,
    respectDNT: true,
    disable: !userConsent
  }}
>
  {children}
</ClickChutneyProvider>

Debugging

Enable debug mode to see tracking events in console:

<ClickChutneyProvider
  config={{
    trackingId: "your-id",
    debug: process.env.NODE_ENV === 'development'
  }}
>
  {children}
</ClickChutneyProvider>

Migration Guide

From Google Analytics

// GA4
gtag('event', 'purchase', { value: 99.99 });

// ClickChutney
track('purchase', { value: 99.99 });

From Mixpanel

// Mixpanel
mixpanel.track('Button Click', { button: 'CTA' });

// ClickChutney  
track('button_click', { button: 'CTA' });

Troubleshooting

Common Issues

1. Events not showing up

// Enable debug mode
<ClickChutneyProvider config={{ debug: true, trackingId: "your-id" }}>

2. Next.js App Router issues

// Ensure provider is in layout.tsx, not page.tsx
// app/layout.tsx ✅
// app/page.tsx ❌

3. SSR warnings

// Use dynamic imports for client-only components
import dynamic from 'next/dynamic';

const ClientOnlyComponent = dynamic(
  () => import('./ClientComponent'),
  { ssr: false }
);

API Reference

Functions

track(eventName, properties?) - Track custom events
pageview(page, properties?) - Track pageviews
identify(traits) - Identify users
reset() - Reset user identity
group(groupId, traits?) - Associate user with group

Hooks

useClickChutney() - Main analytics hook
useEventTracking() - Event tracking utilities
usePageTracking() - Pageview tracking utilities
useUserTracking() - User identification utilities
useFormTracking() - Form tracking utilities
useSession() - Session management

Components

<ClickChutneyProvider> - Analytics provider
<ClickTracker> - Auto-track clicks
<FormTracker> - Auto-track forms

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Support

License

Made with 🍛 by the ClickChutney team. As vibrant and accessible as Indian street food!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ClickChutney React

Features

Compatibility

React Version Support

Next.js Version Support

Installation

Quick Start

1. Wrap your app with the provider

Next.js App Router (app/layout.tsx)

Next.js Pages Router (_app.tsx)

Vite/Create React App

Usage

Manual Event Tracking

Using Hooks (Optional)

Configuration Options

Hooks

useClickChutney()

useEventTracking()

usePageTracking()

useUserTracking()

useFormTracking()

useSession()

Components

ClickTracker

FormTracker

Event Examples

E-commerce Tracking

User Lifecycle

Advanced Examples

E-commerce Tracking

User Journey Tracking

A/B Testing Integration

Server-Side Rendering (SSR)

Environment Variables

TypeScript Support

Performance

Privacy & GDPR Compliance

Debugging

Migration Guide

From Google Analytics

From Mixpanel

Troubleshooting

Common Issues

API Reference

Functions

Hooks

Components

Contributing

Support

License