Package Exports

@click-chutney/clickanalytics
@click-chutney/clickanalytics/dist/clickanalytics.min.js
@click-chutney/clickanalytics/inject
@click-chutney/clickanalytics/react

Readme

ClickAnalytics

A lightweight, privacy-first analytics library inspired by Vercel Analytics. Simple, powerful, and framework-agnostic.

Features

🚀 Zero Configuration - Works out of the box with minimal setup
🔒 Privacy-First - No personal data collection, GDPR compliant
⚡ Lightweight - < 5KB gzipped, minimal performance impact
🎯 Framework Agnostic - Works with React, Next.js, Vue, Svelte, or vanilla JS
🛡️ TypeScript Support - Full type safety included
🔧 Flexible - Multiple integration methods to fit your workflow
📊 Real-time - Events sent immediately for accurate tracking

Quick Start

React/Next.js

npm install @click-chutney/clickanalytics

Add the Analytics component to your app:

import { Analytics } from '@click-chutney/clickanalytics/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics trackingId="your-tracking-id" />
      </body>
    </html>
  );
}

Track custom events with the hook:

import { useAnalytics } from '@click-chutney/clickanalytics/react';

function MyComponent() {
  const analytics = useAnalytics();
  
  const handleClick = () => {
    analytics.event('button_click', { button: 'signup' });
  };
  
  return <button onClick={handleClick}>Sign Up</button>;
}

Vanilla JavaScript

npm install @click-chutney/clickanalytics

import { inject } from '@click-chutney/clickanalytics';

// Initialize
inject({ trackingId: 'your-tracking-id' });

// Track events
import { event } from '@click-chutney/clickanalytics';
event('button_click', { button: 'signup' });

CDN/Script Tag

<script src="https://unpkg.com/@click-chutney/clickanalytics/dist/clickanalytics.min.js"></script>
<meta name="clickanalytics-tracking-id" content="your-tracking-id">

<script>
  // Automatically initialized from meta tag
  // Track custom events
  caPV(); // page view
  caEV('button_click', { button: 'signup' }); // custom event
  caID('user-123'); // identify user
</script>

Installation Methods

Method 1: React/Next.js Component

Perfect for React applications with automatic page view tracking.

// 1. Install the package
npm install @click-chutney/clickanalytics

// 2. Add to your root layout
import { Analytics } from '@click-chutney/clickanalytics/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics trackingId="your-tracking-id" />
      </body>
    </html>
  );
}

// 3. Use the hook for custom events
import { useAnalytics } from '@click-chutney/clickanalytics/react';

function MyComponent() {
  const analytics = useAnalytics();
  
  return (
    <button onClick={() => analytics.event('click', { button: 'cta' })}>
      Click me
    </button>
  );
}

Method 2: Inject Function (Any Framework)

Great for Vue, Svelte, Angular, or vanilla JS applications.

import { inject, event, pageview } from '@click-chutney/clickanalytics';

// Initialize once in your app
inject({ 
  trackingId: 'your-tracking-id',
  debug: true 
});

// Track events anywhere
event('user_signup', { method: 'email' });
pageview('/dashboard');

Method 3: Script Tag (No Build Step)

Perfect for static sites, WordPress, or any HTML page.

<!DOCTYPE html>
<html>
<head>
  <meta name="clickanalytics-tracking-id" content="your-tracking-id">
  <script src="https://unpkg.com/@click-chutney/clickanalytics/dist/clickanalytics.min.js"></script>
</head>
<body>
  <button onclick="caEV('button_click', { button: 'signup' })">
    Sign Up
  </button>
</body>
</html>

API Reference

React Component

<Analytics 
  trackingId="your-id"           // Required: Your tracking ID
  debug={true}                   // Optional: Enable debug logging
  disableInDev={true}           // Optional: Disable in development
  apiUrl="/api/analytics"       // Optional: Custom API endpoint
  beforeSend={(event) => event} // Optional: Modify events before sending
/>

React Hook

const analytics = useAnalytics();

analytics.pageview('/custom-page', 'Custom Title');
analytics.event('custom_event', { key: 'value' });
analytics.identify('user-123');
analytics.flush(); // Force send queued events

Inject Function

import { inject, event, pageview, identify } from '@click-chutney/clickanalytics';

// Initialize
inject({
  trackingId: 'your-tracking-id',
  debug: false,
  disableInDev: true,
  apiUrl: '/api/analytics',
  beforeSend: (event) => {
    // Modify or filter events
    return event;
  }
});

// Track events
pageview(); // Auto-tracks current page
pageview('/custom-path', 'Custom Title');
event('button_click', { button: 'signup' });
identify('user-123');

Script Tag Globals

When using the script tag, these functions are available globally:

caPV(url?, title?)              // Page view
caEV(eventName, properties?)    // Custom event  
caID(userId)                   // Identify user

Configuration

Environment Variables

Set your tracking ID using environment variables:

# React/Next.js
NEXT_PUBLIC_CLICKANALYTICS_ID=your-tracking-id

# Or alternative names
NEXT_PUBLIC_CLICKCHUTNEY_ID=your-tracking-id
CLICKANALYTICS_TRACKING_ID=your-tracking-id

Meta Tag

Add a meta tag to auto-initialize:

<meta name="clickanalytics-tracking-id" content="your-tracking-id">

Advanced Configuration

inject({
  trackingId: 'your-tracking-id',
  debug: true,                    // Enable console logging
  disableInDev: true,            // Disable in development
  apiUrl: '/api/analytics',      // Custom API endpoint
  beforeSend: (event) => {       // Filter/modify events
    // Add custom data
    event.customData = { version: '1.0' };
    
    // Block certain events
    if (event.event === 'spam') return false;
    
    return event;
  }
});

Event Types

Page Views

Automatically tracked when using React component or inject function.

// Manual page view tracking
pageview('/dashboard', 'Dashboard');

Custom Events

Track any user interaction or business event.

event('button_click', {
  button: 'signup',
  location: 'header',
  user_type: 'anonymous'
});

event('purchase', {
  item_id: 'prod_123',
  price: 29.99,
  currency: 'USD'
});

User Identification

Associate events with specific users.

identify('user-123');

// All subsequent events will include this user ID
event('page_view'); // Will include userId: 'user-123'

Integration Examples

Next.js App Router

// app/layout.tsx
import { Analytics } from '@click-chutney/clickanalytics/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  );
}

// app/page.tsx
import { useAnalytics } from '@click-chutney/clickanalytics/react';

export default function HomePage() {
  const analytics = useAnalytics();
  
  return (
    <button onClick={() => analytics.event('cta_click')}>
      Get Started
    </button>
  );
}

Vue.js

// main.js
import { inject } from '@click-chutney/clickanalytics';

inject({ trackingId: 'your-tracking-id' });

// component
import { event } from '@click-chutney/clickanalytics';

export default {
  methods: {
    trackClick() {
      event('button_click', { component: 'header' });
    }
  }
}

Svelte

// app.js
import { inject } from '@click-chutney/clickanalytics';

inject({ trackingId: 'your-tracking-id' });

// Component.svelte
<script>
  import { event } from '@click-chutney/clickanalytics';
  
  function handleClick() {
    event('button_click', { button: 'subscribe' });
  }
</script>

<button on:click={handleClick}>Subscribe</button>

WordPress

<!-- Add to theme header.php or use a plugin -->
<meta name="clickanalytics-tracking-id" content="your-tracking-id">
<script src="https://unpkg.com/@click-chutney/clickanalytics/dist/clickanalytics.min.js"></script>

<!-- Track events in your theme -->
<button onclick="caEV('button_click', { button: 'contact' })">
  Contact Us
</button>

Development

Disable analytics during development:

// Automatically disabled in development
inject({
  trackingId: 'your-tracking-id',
  disableInDev: true // Default: true
});

// Or use environment detection
const isDev = process.env.NODE_ENV === 'development';
if (!isDev) {
  inject({ trackingId: 'your-tracking-id' });
}

ClickAnalytics is designed to be privacy-first:

✅ No personal data collection
✅ No cross-site tracking
✅ No fingerprinting
✅ IP addresses used only for geolocation, not stored
✅ GDPR compliant by design
✅ No third-party cookies

Troubleshooting

Common Issues

1. Events not appearing

Check your tracking ID is correct
Verify network requests in browser dev tools
Enable debug mode: inject({ debug: true })

2. Multiple initializations

Only call inject() once in your app
Use reset() to reinitialize if needed

3. TypeScript errors

Ensure you're importing from the correct path
React components: @click-chutney/clickanalytics/react
Inject functions: @click-chutney/clickanalytics

Debug Mode

Enable debug logging to troubleshoot issues:

inject({
  trackingId: 'your-tracking-id',
  debug: true
});

This will log all events and API calls to the console.

Getting Your Tracking ID

Sign up at clickchutney.com
Create a new project
Copy your tracking ID from the dashboard
Add it to your environment variables or configuration

License

MIT License - see LICENSE file for details.

Support

📧 Email: support@clickchutney.com
🐛 Issues: GitHub Issues
📖 Docs: clickchutney.com/docs

@click-chutney/clickanalytics