--- name: tigr-react description: Analyze a given React / Next.js page or component and add tigr custom analytics events (track / setUser / reset) where they matter. Use when the user says "tigr-react ", "instrument this page", "add tigr events here", "where should I track events", or asks to add custom analytics/events to a React or Next.js screen using the tigr-react SDK. --- # tigr — React / Next.js Instrumentation **Goal:** Take a target page or component, work out which *meaningful* user actions deserve a custom event, explain the plan, then add the `track()` / `setUser()` / `reset()` calls using the `tigr-react` SDK. **Your role:** A pragmatic analytics engineer. You instrument business-meaningful moments — not noise. You never duplicate what the SDK already captures automatically, you never break SSR, and analytics must never crash the app. The user gives you a page/component (a file path, or "this page"). If none is given, ask which one. --- ## Step 0 — Prerequisites (do this first, once per project) 1. **Confirm `tigr-react` is installed.** Check `package.json` dependencies. If missing, stop and tell the user to install it (`npm i tigr-react` / `yarn add tigr-react`). 2. **Confirm the SDK is initialized once at app root.** The shipped API is the zero-boilerplate global — `tigr.initialize(apiKey)` called once on the client, exactly like `OneSignal.initialize`. **There is no provider and no hook to wire** (`tigr-react` exports `tigr`, plus `createTigr` / `TigrClient` for advanced use). Always instrument through the `tigr` global. - **Next.js (App Router):** `initialize()` must run in a **Client Component** (`"use client"`) inside a `useEffect`. The clean pattern is a tiny init component rendered once in `app/layout.tsx`: ```tsx 'use client' import { useEffect } from 'react' import { tigr } from 'tigr-react' export function TigrInit() { useEffect(() => { tigr.initialize(process.env.NEXT_PUBLIC_TIGR_API_KEY!) }, []) return null } ``` ```tsx // app/layout.tsx {children} ``` - **Plain React (Vite / CRA):** call it once in the root component's `useEffect` (usually `App.tsx`): ```tsx useEffect(() => { tigr.initialize(import.meta.env.VITE_TIGR_API_KEY) // Vite; CRA: process.env.REACT_APP_TIGR_API_KEY }, []) ``` - If this call is missing, add it (or tell the user) before instrumenting anything. The API key comes from env (`NEXT_PUBLIC_*` / `VITE_*` / `REACT_APP_*`) — **never hardcode it**. - **Safe by design:** the underlying client is a no-op on the server (importing the module never touches the DOM at import time), and any `tigr.*` method called *before* `initialize()` is a silent no-op. Calls never crash the host app or break SSR. 3. **Pageview is automatic — do NOT wire anything for navigation.** Unlike React Native, the web SDK captures route changes for you: it monkey-patches `history.pushState` / `replaceState` and listens for `popstate`, so **every** SPA navigation (Next.js `` / router, React Router, plain history) fires a `pageview` with no router coupling and no per-page wiring. The single `initialize()` is the whole setup. > The SDK ships a single global — `tigr`. There is no `` / `useTigr()` to set up (README examples that show them predate the shipped API). Always instrument through the `tigr` global. --- ## Step 1 — Analyze the page/component A page is just the root of a tree. The real buttons and forms almost always live several levels down in child components, so you **must walk the whole subtree — recursively — to the leaf components that own the handlers.** Do not stop at the page file or the first level. The event belongs in the component that owns the action, never in a thin wrapper that only lays out children. **How to traverse (do this exhaustively):** 1. Read the page/component file. Note every child component it renders and every `