Koma Analytics – React SDK

Koma Analytics is a lightweight, developer-friendly analytics SDK for React applications. It helps you track user events, identify users, and attach rich user properties with a clean API and minimal setup.

This SDK is designed to feel familiar if you’ve used tools like Amplitude or Mixpanel, while remaining simple and flexible. See features below;

Features

• 🚀 Simple event tracking
• 👤 User identification
• 🧩 User property management
• ⚛️ Built for React (Context + Hooks)
• 🧪 Built-in DevTool for debugging
• 🟦 TypeScript-first
• 📦 Lightweight and tree-shakable

Get Started with Koma Analytics

Create a free Koma Analytics account to start tracking events in your React app.

👉 https://koma-analytics.com

Once you’ve created a project, copy your API Key and API Secret and plug them into KomaProvider.

Installation

npm install @koma-analytics/react-sdk

yarn add @koma-analytics/react-sdk

Quick Start

1. Wrap your app with KomaProvider

Add KomaProvider at the root of your React application.

import { createRoot } from 'react-dom/client';
import { KomaProvider } from '@koma-analytics/react-sdk';

createRoot(document.getElementById('root')!).render(
  <KomaProvider value={{ apiKey: 'YOUR_API_KEY', apiSecret: 'YOUR_API_SECRET' }}>
    <App />
  </KomaProvider>
);

⚠️ All components that use Koma Analytics must be rendered inside KomaProvider.

2. Track events using useKoma

import { useKoma } from '@koma-analytics/react-sdk';

const Example = () => {
  const { track } = useKoma();

  return (
    <button onClick={() => track('button_clicked')}>
      Click me
    </button>
  );
};

KomaProvider

KomaProvider initializes the analytics client and exposes it to your app via React Context.

| Prop | Type | Required | Description. | |------------|------------|----------|----------------------| | apiKey | string | ✅ | Your Koma API key | | apiSecret | string | ✅ | Your Koma API secret | | children | ReactNode | ✅ | Your application |

Example

<KomaProvider value={{ apiKey, apiSecret }}>
  <App />
</KomaProvider>

useKoma Hook

The useKoma hook gives you access to all analytics methods.

const { track, identify, setUserProperty } = useKoma();

❌ Using useKoma outside of a KomaProvider will throw an error.

track(eventName, eventProps?)

Tracks an event with optional properties.

track(eventName: string, eventProps?: Record<string, unknown>): void;

Example

track('page_viewed', {
  page: 'Home',
  referrer: 'Google',
});

identify(userId?)

Identifies the current user by a unique ID.

identify(userId?: string | null): void;

Example

identify('user_123');

Passing null or undefined clears the identified user.

setUserProperty(properties)

Sets or updates properties associated with the current user.

setUserProperty(properties: Record<string, unknown>): void;

Example

setUserProperty({
  plan: 'premium',
  country: 'CM',
});

KomaDevTool

KomaDevTool is an optional developer utility for debugging analytics issues during development.

Usage

import { KomaDevTool } from '@koma-analytics/react-sdk';

<KomaDevTool position="bottom-right" maxErrors={100} />

| Prop | Type | Default. | Description. | |------------|--------------------------------------------------|--------------|-----------------------| | position | bottom-right, bottom-left, top-right or top-left | bottom-right | Position on screen | | maxErrors | number | 50 | Maximum stored errors |

💡 Recommended for development environments only. It doesn't compile for prod.

Error Handling

If useKoma is called outside of KomaProvider, the SDK throws:

Error: useKoma must be used within a KomaProvider

This ensures analytics is always properly initialized.

TypeScript Support

The SDK is fully written in TypeScript and provides strong typings out of the box.

Best Practices

• Initialize KomaProvider once at the root of your app
• Call identify after login or signup
• Use consistent event naming (e.g. snake_case)
• Attach meaningful event properties
• Never send sensitive data (passwords, tokens, secrets)