npm package: @koma-analytics/react-sdk
Description: Koma Analytics React SDK for event tracking and analytics
Author: Fedjio Raymond
Latest version: 0.1.7

# 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

```bash
npm install @koma-analytics/react-sdk
```

```bash
yarn add @koma-analytics/react-sdk
```

## Quick Start

### 1. Wrap your app with KomaProvider

Add KomaProvider at the root of your React application.

```typescript
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

```typescript
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

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

---

### useKoma Hook

The useKoma hook gives you access to all analytics methods.

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

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

---

### track(eventName, eventProps?)

Tracks an event with optional properties.

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

Example

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

---

### identify(userId?)

Identifies the current user by a unique ID.

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

Example

```typescript
identify('user_123');
```

Passing null or undefined clears the identified user.

---

### setUserProperty(properties)

Sets or updates properties associated with the current user.

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

Example

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

---

### KomaDevTool

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

Usage

```typescript
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:

```md
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)

---