Janady13/llms-txt-hub / packages/analytics/README.md

1# @thedaviddias/analytics 2 3Analytics package powered by **OpenPanel**. Drop the provider into your Next.js layout to get pageviews, outbound link tracking, tagged events, and user identification out of the box. 4 5## Exports 6 7| Import path | Description | 8| ------------------------------------------------------ | ------------------------------------------------------------------------ | 9| `@thedaviddias/analytics` | `AnalyticsProvider` — renders OpenPanel script tags | 10| `@thedaviddias/analytics/head` | `AnalyticsHead` — thin wrapper for use inside `<head>` | 11| `@thedaviddias/analytics/server` | `opServer` — server-side OpenPanel SDK singleton | 12| `@thedaviddias/analytics/providers/openpanel-identify` | `OpenPanelIdentify` — client component that syncs auth user to OpenPanel | 13 14## Environment variables 15 16| Variable | Required | Scope | Description | 17| --------------------------------- | ----------------------------- | --------------- | --------------------------------------------------------------- | 18| `NEXT_PUBLIC_OPENPANEL_CLIENT_ID` | Yes (for OpenPanel) | Client + Server | OpenPanel client ID from [openpanel.dev](https://openpanel.dev) | 19| `OPENPANEL_CLIENT_SECRET` | Only for server-side tracking | Server only | OpenPanel client secret (never expose to the browser) | 20 21Both variables must be added to `turbo.json` → `tasks.build.env` so Turborepo invalidates the build cache when they change. 22 23## Setup 24 25### 1. Install the package 26 27```bash 28pnpm add @thedaviddias/analytics 29``` 30 31### 2. Add the provider to your root layout 32 33Place `AnalyticsHead` inside `<head>` and `OpenPanelIdentify` inside `<body>` (within your auth provider tree): 34 35```tsx 36// app/layout.tsx 37import { AnalyticsHead } from '@thedaviddias/analytics/head' 38import { OpenPanelIdentify } from '@thedaviddias/analytics/providers/openpanel-identify' 39 40export default function RootLayout({ children }: { children: React.ReactNode }) { 41 return ( 42 <html lang="en"> 43 <head> 44 <AnalyticsHead 45 openPanelClientId={process.env.NEXT_PUBLIC_OPENPANEL_CLIENT_ID} 46 nonce={nonce} 47 /> 48 </head> 49 <body> 50 {/* Must be inside your auth provider (e.g. ClerkProvider) */} 51 <OpenPanelIdentify /> 52 {children} 53 </body> 54 </html> 55 ) 56} 57``` 58 59### 3. Create the OpenPanel proxy route 60 61Create `app/api/op/[...path]/route.ts` to proxy analytics requests through your own domain (avoids ad blockers): 62 63```ts 64import { createRouteHandler } from '@openpanel/nextjs/server' 65 66export const { GET, POST } = createRouteHandler() 67``` 68 69### 4. Update proxy 70 71Add these to your `proxy.ts`: 72 73- **Public routes**: Add `'/api/op/(.*)'` so the proxy is accessible without auth. 74- **CSP script-src**: Add `https://openpanel.dev` as a fallback origin. 75- **Rate-limit skip**: Exclude `/api/op/` paths from rate limiting. 76 77### 5. Add environment variables to turbo.json 78 79```jsonc 80// turbo.json → tasks.build.env 81"NEXT_PUBLIC_OPENPANEL_CLIENT_ID", 82"OPENPANEL_CLIENT_SECRET", 83``` 84 85## Client-side event tracking 86 87```ts 88import { trackEvent, ANALYTICS_EVENTS } from '@/lib/analytics' 89 90trackEvent(ANALYTICS_EVENTS.WEBSITE_CLICK, { 91 website_name: 'Example', 92 content_slug: 'example-llms-txt' 93}) 94``` 95 96OpenPanel events are only sent in production (`NODE_ENV === 'production'`). 97 98## Server-side event tracking 99 100For API routes and server actions, use the `trackServerEvent` helper with Vercel's `waitUntil`: 101 102```ts 103// lib/openpanel-server.ts 104import { waitUntil } from '@vercel/functions' 105import { opServer } from '@thedaviddias/analytics/server' 106 107export function trackServerEvent(event: string, properties?: Record<string, unknown>) { 108 if (process.env.NODE_ENV !== 'production') return 109 waitUntil(opServer.track(event, properties ?? {})) 110} 111``` 112 113This requires `@vercel/functions` installed in your app and `OPENPANEL_CLIENT_SECRET` set. 114 115## User identification 116 117`OpenPanelIdentify` automatically syncs the authenticated user to OpenPanel using your auth provider's `useAuth()` hook. When a user signs in, it calls `window.op.identify()` with their profile ID, name, and email. On sign-out it calls `window.op.clear()`. 118 119This component must be rendered inside your auth provider tree (e.g. inside `ClerkProvider`). 120 121## How it works 122 123``` 124AnalyticsHead 125 └─ AnalyticsProvider 126 └─ OpenPanelAnalyticsComponent → loads op1.js via /api/op proxy 127 └─ globalProperties: { environment } 128 129OpenPanelIdentify (body) 130 └─ useAuth() → window.op.identify() / window.op.clear() 131 132trackEvent() (client) 133 └─ window.op.track(event, props) [production only] 134 135opServer.track() (server) 136 └─ OpenPanel SDK → direct API call with clientSecret 137``` 138 139## Production guards 140 141OpenPanel tracking is gated behind `process.env.NODE_ENV === 'production'` in three places: 142 1431. **Component rendering** — `AnalyticsProvider` only renders `OpenPanelAnalyticsComponent` in production. 1442. **Client-side tracking** — `trackEvent()` and `AnalyticsLink` skip `window.op.track()` in non-production. 1453. **Server-side tracking** — `trackServerEvent()` returns early in non-production. 146