Add React Analytics

Add React Analytics

Integrate the @temps-sdk/react-analytics SDK into a React application.

> Verified against the real published package. A prior version of this skill documented props and hooks that do not exist (autoTrack={{...}}, debug, useAnalytics() as the accessor, reset, getVisitorId) and broke integrations. Before changing any API here, confirm against the package's type definitions: > ``bash > npm pack @temps-sdk/react-analytics@latest && tar -xzf temps-sdk-react-analytics-*.tgz \ > && cat package/dist/index.d.ts package/dist/types.d.ts package/dist/Provider.d.ts > ` > Trust the .d.ts`, not prose.

Installation

npm install @temps-sdk/react-analytics
# or: yarn add / pnpm add / bun add

Peer deps: React 18 or 19 (react, react-dom).

Two things to know before wiring it up

1. The package already ships 'use client' at the top of its build. In the Next.js App Router you import TempsAnalyticsProvider directly into your Server Component layout.tsx — you do not need to author your own 'use client' wrapper component around it.
2. ignoreLocalhost defaults to true → the SDK sends nothing while running on localhost. Correct for production, but it means you see no network requests in local dev. Pass ignoreLocalhost={false} only when you explicitly want to test locally.

basePath: what to set

The SDK POSTs to ${basePath}/event, ${basePath}/speed, ${basePath}/heartbeat, and session replay to ${basePath}/session-replay (via sendBeacon, falling back to keepalive fetch).

• App deployed on Temps → no basePath is required. The SDK default is /api/_temps, and the Temps proxy treats /api/_temps/* as a public ingest path: it bypasses the auth gate from any host and routes to the platform's analytics handlers. No app-side route handler is needed.
• App NOT on Temps → ${basePath}/... hits your own origin. You must either run a route that forwards to Temps, or point basePath at an absolute Temps ingest URL, and set domain="" so events are attributed correctly.

The package's built-in default basePath is /api/_temps. Set basePath only when the app needs a custom same-origin proxy path.

Framework Setup

Next.js App Router (13+)

// app/layout.tsx — stays a Server Component; the provider carries its own 'use client'.
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    
      
        
          {children}
        
      
    
  );
}

Next.js Pages Router

// pages/_app.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    
      
    
  );
}

Vite / Create React App

// src/main.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

ReactDOM.createRoot(document.getElementById('root')!).render(
  
    
  
);

Remix

// app/root.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

export default function App() {
  return (
    
      
        
          
        
      
    
  );
}

Provider Configuration — real props (all flat, all optional)

  {children}

> ⚠️ There is no nested autoTrack={{ ... }} prop and no debug prop. Old docs that show those are wrong.

Available Hooks

Full signatures and examples in [HOOKSREFERENCE.md](references/HOOKSREFERENCE.md).

| Export | Returns | Purpose | |--------|---------|---------| | useTrackEvent() | (eventName, data?) => Promise | Custom events | | useTempsAnalytics() | { trackEvent, identify, trackPageview, enabled } | The context accessor | | useTrackPageview() | () => void | Manual pageviews | | usePageLeave(options?) | { triggerPageLeave } | Page-leave / time-on-page | | useEngagementTracking(options?) | { engagementData, isTracking } | Heartbeat engagement | | useSpeedAnalytics(options?) | void | Web Vitals (TTFB, LCP, FID, FCP, CLS, INP) | | useScrollVisibility(options?) | ref callback | Fires an event when the element scrolls into view | | useAnalytics(options) | { track, identify } | ⚠️ Standalone generic helper that requires { client } — NOT the context accessor |

> ⚠️ The context accessor is useTempsAnalytics(), not useAnalytics(). useAnalytics(options) is a different, generic hook that throws without a { client } argument. reset() and getVisitorId() do not exist.

Track Custom Events

'use client';
import { useTrackEvent } from '@temps-sdk/react-analytics';

function SubscribeButton() {
  const trackEvent = useTrackEvent();
  return (
     trackEvent('button_click', { button_id: 'subscribe', plan: 'premium' })}>
      Subscribe
    
  );
}

Identify Users — status: NOT YET FUNCTIONAL

identify(userId, traits) is exposed on the context (useTempsAnalytics().identify) but the current SDK implements it as a no-op placeholder ("implement when identity endpoint is available"). Do not tell the user identification works yet. Attach user attributes as event_data on trackEvent calls instead:

'use client';
import { useTrackEvent } from '@temps-sdk/react-analytics';

const trackEvent = useTrackEvent();
trackEvent('signed_in', { user_id: user.id, plan: user.plan });

When the identity endpoint ships, switch to useTempsAnalytics().identify(...).

Session Recording

Session recording is configured on the main provider via enableSessionRecording + sessionRecordingConfig. See [SESSIONRECORDING.md](references/SESSIONRECORDING.md).

  {children}

A separate SessionRecordingProvider + useSessionRecordingControl exist for user-toggleable recording (consent flows). Their real APIs (defaultEnabled/persistPreference, and { isEnabled, enable, disable, toggle }) are documented in [SESSIONRECORDING.md](references/SESSIONRECORDING.md) — they are NOT enabled/maskAllInputs/startRecording.

Verification Checklist

1. On localhost: with ignoreLocalhost default true you'll see nothing — expected. Temporarily set ignoreLocalhost={false} to verify wiring.
2. DevTools → Network: confirm POSTs to /api/_temps/event (and /speed, /heartbeat) on navigation and interaction.
3. Confirm responses are 2xx (when Temps-hosted, the proxy accepts them from any host).
4. Check the Temps dashboard for incoming events / Web Vitals / session replays.
5. Run npx tsc --noEmit — it catches prop/hook drift immediately.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gotempsh
• Source: gotempsh/temps
• License: Apache-2.0
• Homepage: https://temps.sh/docs

Install and usage instructions live in the source repository linked above.