@serge-ai/react

No cookies. No localStorage by default. No consent banner required. ePrivacy Art. 5(3) compliant by construction.

React integration for Serge — drop-in <Analytics /> and <DetectionPixel /> components for catching AI-agent sessions on your site.

pnpm add @serge-ai/react
# or
npm install @serge-ai/react

For Next.js App Router consumers → use @serge-ai/nextjs instead — it auto-tracks route changes via usePathname / useSearchParams.

For vanilla JS / Vue / Svelte → use @serge-ai/js.

Quick start

import { Analytics, DetectionPixel, track } from '@serge-ai/react'

export function App() {
  return (
    <>
      <Analytics token="srg_pub_xxxxxxxxxxxxxxxxxxxxxxxxxx" />
      <DetectionPixel token="srg_pub_xxxxxxxxxxxxxxxxxxxxxxxxxx" />
      <button onClick={() => track('signup_clicked')}>Sign up</button>
    </>
  )
}

<Analytics /> catches JS-driven agents (browser extensions, browser-use, Operator, ChatGPT Atlas, Claude Computer Use). <DetectionPixel /> catches HTML-only agents that don't execute JS (ChatGPT-User, Claude-User, GPTBot, ClaudeBot, PerplexityBot). The pixel is what makes Serge see traffic that PostHog, GA4, and Hotjar miss entirely.

Components

<Analytics />

Drop-in component. Calls init() once on mount, returns null.

<Analytics
  token="srg_pub_xxx"
  apiBase="https://serge.ai"  // optional first-party proxy override
  debug={false}                // optional
  requireConsent={false}       // optional
/>

Re-renders only re-call init() if the token changes. Other config edits require a remount — the tracker's runtime state is module-level and changing flags mid-session produces unpredictable behavior.

<DetectionPixel />

Renders an invisible 1×1 GIF that catches non-JS agents. Drop next to <Analytics />.

<DetectionPixel
  token="srg_pub_xxx"
  apiBase="https://serge.ai"   // optional
/>

The image fetch fires from the agent direct to the Serge ingest endpoint with the agent's User-Agent intact. Serge's server matches the UA against known agent patterns (ChatGPT-User, Claude-User, GPTBot, ClaudeBot, PerplexityBot, …), validates the Referer against your registered domain, then writes the hit to your dashboard. No competing analytics SDK ships this.

API re-exports

import { init, track, consent, pageview } from '@serge-ai/react'

These are re-exports from @serge-ai/js so consumers can import everything from one path. See @serge-ai/js docs for the full reference.

SSR safety

Every browser-API access is guarded inside useEffect. Components are marked 'use client'. Safe to import from server components, RSC layouts, Edge runtimes.

Why no <TrackerProvider> / useTracker() hook?

PostHog tried both patterns; the convergent industry pattern is the singleton init() + import-anywhere model (Sentry, Mixpanel, Amplitude, Segment all do this). The provider+hook adds context-render overhead without giving the consumer anything they couldn't get from the singleton import. We dropped them in 0.2.0.

Why no identify()?

Serge measures agent sessions, not end-users. Per-user identity is anti-goal for cookieless agent analytics. See @serge-ai/js README for the reasoning.

React versions

react@^18 || ^19 (peer dependency). Works in both 18 and 19.

Bundle size

Under 6 KB gzipped (excluding react and @serge-ai/js, which the host already provides). size-limit enforces this in CI.

License

MIT © Superstellar LLC. See LICENSE.