tigr-react

v0.2.0

Published

2 days ago

tigr analytics SDK for React & Next.js — drop-in auto-capture of user behaviour.

0High
0Medium
0Low

tigr is a product analytics platform that turns raw events into clear, actionable insights. No charts to decode, no data team required you install the SDK, and tigr does the rest. This package is the React/Next.js client.

Install

npm install tigr-react

Quick start

Wrap your app in <TigrProvider> with your project API key. That's it page views, clicks, rage clicks, scroll depth and errors are captured automatically.

Next.js (App Router)

// app/layout.tsx
import { TigrProvider } from 'tigr-react'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <TigrProvider config={{ apiKey: 'tigr_pk_...' }}>
          {children}
        </TigrProvider>
      </body>
    </html>
  )
}

React

import { TigrProvider } from 'tigr-react'

function App() {
  return (
    <TigrProvider config={{ apiKey: 'tigr_pk_...' }}>
      <YourApp />
    </TigrProvider>
  )
}

Get your API key from your project's Settings at usetigr.app.

Tracking custom events

Grab the client anywhere with useTigr():

import { useTigr } from 'tigr-react'

function CheckoutButton() {
  const tigr = useTigr()

  return (
    <button onClick={() => tigr.track('checkout_started', { plan: 'pro', total: 49 })}>
      Buy
    </button>
  )
}

Identifying users

Attach a stable user id (and optional traits) so events are tied to a person:

const tigr = useTigr()

// after login
tigr.setUser('user_123', { email: '[email protected]', plan: 'pro' })

// on logout
tigr.reset()

identify() is the same as setUser() — use whichever reads better.

Configuration

<TigrProvider
  config={{
    apiKey: 'tigr_pk_...',
    autoCapture: true,        // true | false | { pageview, rageClick, scrollDepth, error, pageLeave }
    flushInterval: 2000,      // ms before a buffered batch is sent (default 2000)
    batchSize: 20,            // force a flush at this many events (default 20)
    debug: false,             // log every event + flush to the console
    devMode: false,           // when true, the SDK does nothing (use in development)
  }}
>

| Option | Type | Default | Description | | --------------- | ------------------------------------- | ------- | ----------- | | apiKey | string | — | Required. Your project API key. | | host | string | tigr cloud | Where events are sent. Override to point at a self-hosted / local ingestion service. | | autoCapture | boolean \| Partial<AutoCaptureOptions> | true | Toggle automatic signals individually or all at once. | | flushInterval | number | 2000 | Ms to wait after the first buffered event before sending. | | batchSize | number | 20 | Flush immediately once the queue reaches this size. | | debug | boolean | false | Console-log every event and flush. | | devMode | boolean | false | When true the SDK does nothing — no capture, no network. Turn it on in development so your own activity doesn't pollute analytics. |

Auto-captured signals

pageview · rageClick · scrollDepth · error · pageLeave — all on by default. Turn any off:

<TigrProvider config={{ apiKey: 'tigr_pk_...', autoCapture: { scrollDepth: false } }}>

Self-hosting / local development

By default events go to tigr's hosted ingestion endpoint. Point the SDK somewhere else with host — handy when running the ingestion service locally:

<TigrProvider config={{ apiKey: 'tigr_pk_...', host: 'http://localhost:4001' }}>

Set host: '' (empty string) to run in console-only mode — events are logged but nothing is sent. Omit host entirely to use the default tigr cloud.

API

useTigr() returns the client:

| Method | Description | | ------ | ----------- | | track(name, properties?) | Send a custom event. | | identify(userId, traits?) | Tie events to a user. | | setUser(userId, traits?) | Alias for identify. | | reset() | Clear the current user (e.g. on logout). | | flush() | Send everything queued right now. |

SSR

<TigrProvider> is SSR-safe — on the server the client is a no-op, so capture only runs in the browser. In the Next.js App Router it must live in a Client Component; this package already ships the "use client" directive, so you can drop it straight into app/layout.tsx.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme