@codeswayam/analytics 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +479 -79
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,145 +1,545 @@
|
|
|
1
1
|
# @codeswayam/analytics
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@codeswayam/analytics)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
[](https://react.dev/)
|
|
7
|
+
[](https://bundlephobia.com/package/@codeswayam/analytics)
|
|
4
8
|
|
|
5
|
-
Centralized analytics and tracking
|
|
9
|
+
> Centralized analytics and event tracking for all CodeSwayam applications. Drop-in React component for automatic page views with support for custom events and server-side tracking.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Table of Contents
|
|
14
|
+
|
|
15
|
+
- [Overview](#overview)
|
|
16
|
+
- [Installation](#installation)
|
|
17
|
+
- [Peer Dependencies](#peer-dependencies)
|
|
18
|
+
- [Architecture](#architecture)
|
|
19
|
+
- [API Reference](#api-reference)
|
|
20
|
+
- [Analytics Component](#analytics-component)
|
|
21
|
+
- [Client-Side Tracking](#client-side-tracking)
|
|
22
|
+
- [Server-Side Tracking](#server-side-tracking)
|
|
23
|
+
- [TypeScript Types](#typescript-types)
|
|
24
|
+
- [Code Examples](#code-examples)
|
|
25
|
+
- [Integration Guide](#integration-guide)
|
|
26
|
+
- [Compatibility Matrix](#compatibility-matrix)
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Overview
|
|
31
|
+
|
|
32
|
+
`@codeswayam/analytics` is the single analytics integration layer for the entire CodeSwayam platform. Rather than each app implementing its own tracking setup, this package provides:
|
|
33
|
+
|
|
34
|
+
- A **zero-config `<Analytics />` component** — automatically tracks page views on route changes
|
|
35
|
+
- **Custom event tracking** functions for user actions and feature usage
|
|
36
|
+
- **Server-side tracking** utilities for SSR apps (Next.js App Router server components, API routes)
|
|
37
|
+
- React 19 compatible with no deprecated APIs
|
|
38
|
+
|
|
39
|
+
The package is intentionally lightweight, with the analytics provider configuration centralized in this package so all apps stay in sync.
|
|
6
40
|
|
|
7
41
|
---
|
|
8
42
|
|
|
9
43
|
## Installation
|
|
10
44
|
|
|
11
45
|
```bash
|
|
46
|
+
# npm
|
|
12
47
|
npm install @codeswayam/analytics
|
|
48
|
+
|
|
49
|
+
# yarn
|
|
50
|
+
yarn add @codeswayam/analytics
|
|
51
|
+
|
|
52
|
+
# pnpm
|
|
53
|
+
pnpm add @codeswayam/analytics
|
|
13
54
|
```
|
|
14
55
|
|
|
15
|
-
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Peer Dependencies
|
|
59
|
+
|
|
60
|
+
| Dependency | Version | Purpose |
|
|
61
|
+
|---|---|---|
|
|
62
|
+
| `react` | `^18.0.0 \|\| ^19.0.0` | React runtime (for `<Analytics />` component) |
|
|
63
|
+
| `react-dom` | `^18.0.0 \|\| ^19.0.0` | DOM bindings |
|
|
64
|
+
| `next` | `^14.0.0 \|\| ^15.0.0` | Required only for Next.js router integration |
|
|
65
|
+
|
|
66
|
+
Install required peer dependencies:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
npm install react react-dom
|
|
70
|
+
```
|
|
16
71
|
|
|
17
72
|
---
|
|
18
73
|
|
|
19
|
-
##
|
|
74
|
+
## Architecture
|
|
20
75
|
|
|
21
|
-
|
|
76
|
+
```
|
|
77
|
+
packages/analytics/src/
|
|
78
|
+
├── index.tsx — Main exports: Analytics component + client tracking functions
|
|
79
|
+
├── Analytics.tsx — React component: automatic page view tracking (5.7 KB)
|
|
80
|
+
└── server.ts — Server-side tracking utilities (1.5 KB)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
**Entry points:**
|
|
84
|
+
|
|
85
|
+
| Import Path | Contents |
|
|
86
|
+
|---|---|
|
|
87
|
+
| `@codeswayam/analytics` | `<Analytics />` component + client-side event tracking |
|
|
88
|
+
| `@codeswayam/analytics/server` | Server-side tracking utilities (Node.js only) |
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## API Reference
|
|
93
|
+
|
|
94
|
+
### Analytics Component
|
|
22
95
|
|
|
23
96
|
```tsx
|
|
24
|
-
// app/layout.tsx
|
|
25
97
|
import { Analytics } from '@codeswayam/analytics';
|
|
98
|
+
```
|
|
26
99
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
100
|
+
A React component that initializes the analytics provider and automatically fires a page view event on every route change.
|
|
101
|
+
|
|
102
|
+
| Prop | Type | Required | Default | Description |
|
|
103
|
+
|---|---|---|---|---|
|
|
104
|
+
| `debug` | `boolean` | ❌ | `false` | Log all tracked events to the console |
|
|
105
|
+
| `disabled` | `boolean` | ❌ | `false` | Disable all tracking (useful for test/CI environments) |
|
|
106
|
+
|
|
107
|
+
Renders nothing to the DOM. Place it once in your root layout — it handles everything automatically.
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
### Client-Side Tracking
|
|
112
|
+
|
|
113
|
+
Imported from `@codeswayam/analytics`:
|
|
114
|
+
|
|
115
|
+
#### `trackEvent(name, properties?)`
|
|
116
|
+
|
|
117
|
+
Track a custom user action or feature interaction.
|
|
118
|
+
|
|
119
|
+
| Parameter | Type | Required | Description |
|
|
120
|
+
|---|---|---|---|
|
|
121
|
+
| `name` | `string` | ✅ | Event name (e.g., `'agent_created'`, `'workflow_run'`) |
|
|
122
|
+
| `properties` | `Record<string, unknown>` | ❌ | Additional key-value metadata for the event |
|
|
123
|
+
|
|
124
|
+
#### `trackPageView(url?)`
|
|
125
|
+
|
|
126
|
+
Manually fire a page view event. The `<Analytics />` component calls this automatically on route changes — use this only when you need manual control.
|
|
127
|
+
|
|
128
|
+
| Parameter | Type | Required | Description |
|
|
129
|
+
|---|---|---|---|
|
|
130
|
+
| `url` | `string` | ❌ | Page URL (defaults to `window.location.href`) |
|
|
131
|
+
|
|
132
|
+
#### `identify(userId, traits?)`
|
|
133
|
+
|
|
134
|
+
Associate subsequent events with a specific user identity.
|
|
135
|
+
|
|
136
|
+
| Parameter | Type | Required | Description |
|
|
137
|
+
|---|---|---|---|
|
|
138
|
+
| `userId` | `string` | ✅ | Your internal user ID |
|
|
139
|
+
| `traits` | `Record<string, unknown>` | ❌ | User attributes (name, email, plan, etc.) |
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
### Server-Side Tracking
|
|
144
|
+
|
|
145
|
+
Import from `@codeswayam/analytics/server` in server components, API routes, or middleware:
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
import { trackServerEvent, trackServerPageView } from '@codeswayam/analytics/server';
|
|
45
149
|
```
|
|
46
150
|
|
|
47
|
-
|
|
151
|
+
#### `trackServerEvent(name, properties?, context?)`
|
|
152
|
+
|
|
153
|
+
Track an event from a server context (API route, server action, middleware).
|
|
154
|
+
|
|
155
|
+
| Parameter | Type | Required | Description |
|
|
156
|
+
|---|---|---|---|
|
|
157
|
+
| `name` | `string` | ✅ | Event name |
|
|
158
|
+
| `properties` | `Record<string, unknown>` | ❌ | Event metadata |
|
|
159
|
+
| `context` | `ServerTrackingContext` | ❌ | Request context (userId, IP, user-agent) |
|
|
160
|
+
|
|
161
|
+
Returns `Promise<void>`.
|
|
162
|
+
|
|
163
|
+
#### `trackServerPageView(url, context?)`
|
|
164
|
+
|
|
165
|
+
Track a server-rendered page view (e.g., from middleware or a server component).
|
|
166
|
+
|
|
167
|
+
| Parameter | Type | Required | Description |
|
|
168
|
+
|---|---|---|---|
|
|
169
|
+
| `url` | `string` | ✅ | The page URL |
|
|
170
|
+
| `context` | `ServerTrackingContext` | ❌ | Request context |
|
|
171
|
+
|
|
172
|
+
Returns `Promise<void>`.
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## TypeScript Types
|
|
177
|
+
|
|
178
|
+
```typescript
|
|
179
|
+
// Props for the <Analytics /> component
|
|
180
|
+
interface AnalyticsProps {
|
|
181
|
+
debug?: boolean;
|
|
182
|
+
disabled?: boolean;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
// Custom event tracking
|
|
186
|
+
interface TrackEventOptions {
|
|
187
|
+
name: string;
|
|
188
|
+
properties?: Record<string, unknown>;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
// Server-side context
|
|
192
|
+
interface ServerTrackingContext {
|
|
193
|
+
userId?: string;
|
|
194
|
+
anonymousId?: string;
|
|
195
|
+
ip?: string;
|
|
196
|
+
userAgent?: string;
|
|
197
|
+
referrer?: string;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
// Page view
|
|
201
|
+
interface PageViewEvent {
|
|
202
|
+
url: string;
|
|
203
|
+
referrer?: string;
|
|
204
|
+
title?: string;
|
|
205
|
+
}
|
|
206
|
+
```
|
|
48
207
|
|
|
49
208
|
---
|
|
50
209
|
|
|
51
|
-
##
|
|
210
|
+
## Code Examples
|
|
211
|
+
|
|
212
|
+
### 1. Installation
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
npm install @codeswayam/analytics
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
For Next.js projects with server-side tracking:
|
|
52
219
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
| `ga4Id` | `string` | GA4 Measurement ID (e.g. `G-XXXXXXXXXX`). Skipped if `gtmId` is set — GTM handles GA4 |
|
|
57
|
-
| `metaPixelId` | `string` | Meta (Facebook) Pixel ID |
|
|
58
|
-
| `gscVerification` | `string` | Google Search Console meta verification code |
|
|
59
|
-
| `hotjarId` | `string` | Hotjar Site ID |
|
|
60
|
-
| `clarityId` | `string` | Microsoft Clarity Project ID |
|
|
61
|
-
| `appName` | `string` | Pushed to `dataLayer` as `appName` for GTM filtering across apps |
|
|
220
|
+
```bash
|
|
221
|
+
npm install @codeswayam/analytics react react-dom
|
|
222
|
+
```
|
|
62
223
|
|
|
63
224
|
---
|
|
64
225
|
|
|
65
|
-
|
|
226
|
+
### 2. App Layout Integration (`<Analytics />`)
|
|
66
227
|
|
|
67
|
-
|
|
228
|
+
Add `<Analytics />` once to your root layout. It fires page views automatically on every navigation.
|
|
68
229
|
|
|
69
|
-
|
|
70
|
-
// app/layout.tsx (server component)
|
|
71
|
-
import { Analytics, getAnalyticsConfig } from '@codeswayam/analytics';
|
|
230
|
+
**Next.js App Router (`app/layout.tsx`):**
|
|
72
231
|
|
|
73
|
-
|
|
74
|
-
|
|
232
|
+
```tsx
|
|
233
|
+
import { Analytics } from '@codeswayam/analytics';
|
|
234
|
+
import type { ReactNode } from 'react';
|
|
75
235
|
|
|
236
|
+
export default function RootLayout({ children }: { children: ReactNode }) {
|
|
76
237
|
return (
|
|
77
|
-
<html>
|
|
238
|
+
<html lang="en">
|
|
78
239
|
<body>
|
|
79
|
-
<Analytics {...config} appName="web" />
|
|
80
240
|
{children}
|
|
241
|
+
{/* Analytics component — renders nothing, tracks automatically */}
|
|
242
|
+
<Analytics />
|
|
81
243
|
</body>
|
|
82
244
|
</html>
|
|
83
245
|
);
|
|
84
246
|
}
|
|
85
247
|
```
|
|
86
248
|
|
|
87
|
-
|
|
249
|
+
**Next.js Pages Router (`pages/_app.tsx`):**
|
|
88
250
|
|
|
89
|
-
|
|
251
|
+
```tsx
|
|
252
|
+
import { Analytics } from '@codeswayam/analytics';
|
|
253
|
+
import type { AppProps } from 'next/app';
|
|
90
254
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
255
|
+
export default function App({ Component, pageProps }: AppProps) {
|
|
256
|
+
return (
|
|
257
|
+
<>
|
|
258
|
+
<Component {...pageProps} />
|
|
259
|
+
<Analytics />
|
|
260
|
+
</>
|
|
261
|
+
);
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
**Vite / React SPA (`src/main.tsx`):**
|
|
266
|
+
|
|
267
|
+
```tsx
|
|
268
|
+
import { Analytics } from '@codeswayam/analytics';
|
|
269
|
+
import { BrowserRouter } from 'react-router-dom';
|
|
270
|
+
import { App } from './App';
|
|
271
|
+
|
|
272
|
+
ReactDOM.createRoot(document.getElementById('root')!).render(
|
|
273
|
+
<BrowserRouter>
|
|
274
|
+
<App />
|
|
275
|
+
<Analytics />
|
|
276
|
+
</BrowserRouter>,
|
|
277
|
+
);
|
|
278
|
+
```
|
|
98
279
|
|
|
99
280
|
---
|
|
100
281
|
|
|
101
|
-
|
|
282
|
+
### 3. Custom Event Tracking
|
|
102
283
|
|
|
103
|
-
|
|
284
|
+
Track meaningful user actions throughout your application:
|
|
285
|
+
|
|
286
|
+
```typescript
|
|
104
287
|
import { trackEvent } from '@codeswayam/analytics';
|
|
105
288
|
|
|
106
|
-
//
|
|
107
|
-
|
|
289
|
+
// Track when a user creates an agent
|
|
290
|
+
async function handleCreateAgent(formData: CreateAgentFormData) {
|
|
291
|
+
const agent = await apiClient.agents.create(formData);
|
|
292
|
+
|
|
293
|
+
trackEvent('agent_created', {
|
|
294
|
+
agentId: agent.id,
|
|
295
|
+
agentName: agent.name,
|
|
296
|
+
model: agent.model,
|
|
297
|
+
});
|
|
298
|
+
|
|
299
|
+
return agent;
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
// Track feature usage
|
|
303
|
+
function handleWorkflowRun(workflowId: string) {
|
|
304
|
+
trackEvent('workflow_run_started', {
|
|
305
|
+
workflowId,
|
|
306
|
+
source: 'dashboard',
|
|
307
|
+
});
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
// Track subscription events
|
|
311
|
+
function handleUpgrade(plan: string) {
|
|
312
|
+
trackEvent('plan_upgrade_clicked', {
|
|
313
|
+
targetPlan: plan,
|
|
314
|
+
currentPlan: user.plan,
|
|
315
|
+
});
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
// Track errors
|
|
319
|
+
function handleApiError(error: Error, context: string) {
|
|
320
|
+
trackEvent('api_error', {
|
|
321
|
+
errorMessage: error.message,
|
|
322
|
+
context,
|
|
323
|
+
timestamp: new Date().toISOString(),
|
|
324
|
+
});
|
|
325
|
+
}
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
---
|
|
329
|
+
|
|
330
|
+
### 4. Server-Side Tracking
|
|
331
|
+
|
|
332
|
+
Use server-side utilities in Next.js API routes, server actions, or middleware:
|
|
333
|
+
|
|
334
|
+
**Next.js API Route (`app/api/agents/route.ts`):**
|
|
335
|
+
|
|
336
|
+
```typescript
|
|
337
|
+
import { trackServerEvent } from '@codeswayam/analytics/server';
|
|
338
|
+
import { NextRequest, NextResponse } from 'next/server';
|
|
339
|
+
|
|
340
|
+
export async function POST(req: NextRequest) {
|
|
341
|
+
const body = await req.json();
|
|
342
|
+
const userId = req.headers.get('x-user-id') ?? undefined;
|
|
343
|
+
|
|
344
|
+
// Create the agent
|
|
345
|
+
const agent = await db.agents.create(body);
|
|
346
|
+
|
|
347
|
+
// Track on the server (no client-side JS needed)
|
|
348
|
+
await trackServerEvent('agent_created', {
|
|
349
|
+
agentId: agent.id,
|
|
350
|
+
model: agent.model,
|
|
351
|
+
}, {
|
|
352
|
+
userId,
|
|
353
|
+
ip: req.ip,
|
|
354
|
+
userAgent: req.headers.get('user-agent') ?? undefined,
|
|
355
|
+
});
|
|
356
|
+
|
|
357
|
+
return NextResponse.json(agent);
|
|
358
|
+
}
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
**Next.js Server Action (`app/actions/billing.ts`):**
|
|
362
|
+
|
|
363
|
+
```typescript
|
|
364
|
+
'use server';
|
|
365
|
+
|
|
366
|
+
import { trackServerEvent } from '@codeswayam/analytics/server';
|
|
367
|
+
import { auth } from '@/lib/auth';
|
|
368
|
+
|
|
369
|
+
export async function upgradePlan(planId: string) {
|
|
370
|
+
const session = await auth();
|
|
371
|
+
|
|
372
|
+
// Process the upgrade
|
|
373
|
+
const result = await billing.upgrade(session.user.id, planId);
|
|
374
|
+
|
|
375
|
+
// Track from the server
|
|
376
|
+
await trackServerEvent('subscription_upgraded', {
|
|
377
|
+
planId,
|
|
378
|
+
userId: session.user.id,
|
|
379
|
+
previousPlan: session.user.plan,
|
|
380
|
+
}, {
|
|
381
|
+
userId: session.user.id,
|
|
382
|
+
});
|
|
383
|
+
|
|
384
|
+
return result;
|
|
385
|
+
}
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
**Next.js Middleware (`middleware.ts`):**
|
|
389
|
+
|
|
390
|
+
```typescript
|
|
391
|
+
import { trackServerPageView } from '@codeswayam/analytics/server';
|
|
392
|
+
import { type NextRequest, NextResponse } from 'next/server';
|
|
393
|
+
|
|
394
|
+
export async function middleware(req: NextRequest) {
|
|
395
|
+
// Track server-side page views for SSR accuracy
|
|
396
|
+
await trackServerPageView(req.nextUrl.pathname, {
|
|
397
|
+
userAgent: req.headers.get('user-agent') ?? undefined,
|
|
398
|
+
referrer: req.headers.get('referer') ?? undefined,
|
|
399
|
+
});
|
|
400
|
+
|
|
401
|
+
return NextResponse.next();
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
export const config = {
|
|
405
|
+
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
|
|
406
|
+
};
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
---
|
|
410
|
+
|
|
411
|
+
### 5. User Identification
|
|
412
|
+
|
|
413
|
+
Identify users after authentication to associate events with specific accounts:
|
|
414
|
+
|
|
415
|
+
```typescript
|
|
416
|
+
import { identify } from '@codeswayam/analytics';
|
|
417
|
+
|
|
418
|
+
// After successful login
|
|
419
|
+
async function handleLoginSuccess(user: User) {
|
|
420
|
+
identify(user.id, {
|
|
421
|
+
name: user.name,
|
|
422
|
+
email: user.email,
|
|
423
|
+
plan: user.subscription.plan,
|
|
424
|
+
company: user.organization?.name,
|
|
425
|
+
createdAt: user.createdAt,
|
|
426
|
+
});
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
// After signup
|
|
430
|
+
async function handleSignupSuccess(user: User) {
|
|
431
|
+
identify(user.id, {
|
|
432
|
+
name: user.name,
|
|
433
|
+
email: user.email,
|
|
434
|
+
plan: 'trial',
|
|
435
|
+
signupSource: user.referralSource,
|
|
436
|
+
});
|
|
437
|
+
|
|
438
|
+
trackEvent('signup_completed', {
|
|
439
|
+
method: 'email',
|
|
440
|
+
referralSource: user.referralSource,
|
|
441
|
+
});
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
// On logout — reset identity
|
|
445
|
+
async function handleSignOut() {
|
|
446
|
+
// No explicit reset needed; next session will create a new anonymous ID
|
|
447
|
+
await signOut();
|
|
448
|
+
}
|
|
108
449
|
```
|
|
109
450
|
|
|
110
|
-
|
|
451
|
+
---
|
|
452
|
+
|
|
453
|
+
### 6. Debug Mode
|
|
454
|
+
|
|
455
|
+
Enable debug mode during development to log all events to the browser console:
|
|
111
456
|
|
|
112
457
|
```tsx
|
|
113
|
-
|
|
458
|
+
// Only enable in development
|
|
459
|
+
<Analytics debug={process.env.NODE_ENV === 'development'} />
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
Console output in debug mode:
|
|
463
|
+
|
|
464
|
+
```
|
|
465
|
+
[Analytics] page_view { url: '/dashboard', referrer: '/login', title: 'Dashboard' }
|
|
466
|
+
[Analytics] agent_created { agentId: 'agent_123', model: 'gpt-4o' }
|
|
467
|
+
[Analytics] workflow_run_started { workflowId: 'wf_456', source: 'dashboard' }
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
---
|
|
114
471
|
|
|
115
|
-
|
|
116
|
-
|
|
472
|
+
### 7. Disabling in Test Environments
|
|
473
|
+
|
|
474
|
+
Prevent analytics events from firing during automated tests:
|
|
475
|
+
|
|
476
|
+
```tsx
|
|
477
|
+
// Disable analytics in test environments
|
|
478
|
+
<Analytics disabled={process.env.NODE_ENV === 'test'} />
|
|
117
479
|
```
|
|
118
480
|
|
|
119
|
-
|
|
481
|
+
Or with an environment variable:
|
|
482
|
+
|
|
483
|
+
```tsx
|
|
484
|
+
<Analytics disabled={process.env.NEXT_PUBLIC_ANALYTICS_DISABLED === 'true'} />
|
|
485
|
+
```
|
|
120
486
|
|
|
121
487
|
---
|
|
122
488
|
|
|
123
|
-
##
|
|
489
|
+
## Integration Guide
|
|
490
|
+
|
|
491
|
+
### Next.js App Router (Recommended)
|
|
492
|
+
|
|
493
|
+
1. Install the package
|
|
494
|
+
2. Add `<Analytics />` to `app/layout.tsx`
|
|
495
|
+
3. Import server utilities from `@codeswayam/analytics/server` in server files
|
|
496
|
+
4. Call `trackEvent()` in client components and `trackServerEvent()` in server code
|
|
497
|
+
|
|
498
|
+
### Next.js Pages Router
|
|
499
|
+
|
|
500
|
+
1. Install the package
|
|
501
|
+
2. Add `<Analytics />` to `pages/_app.tsx`
|
|
502
|
+
3. Call `trackEvent()` in any client-side component or page
|
|
503
|
+
|
|
504
|
+
### Vite / Create React App
|
|
505
|
+
|
|
506
|
+
1. Install the package
|
|
507
|
+
2. Add `<Analytics />` near the root of your component tree (inside your router)
|
|
508
|
+
3. Call `trackEvent()` anywhere in client code
|
|
509
|
+
|
|
510
|
+
### Environment Variables
|
|
511
|
+
|
|
512
|
+
The package reads the following optional environment variables:
|
|
124
513
|
|
|
125
514
|
| Variable | Description |
|
|
126
|
-
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `NEXT_PUBLIC_META_PIXEL_ID` | Meta Pixel ID |
|
|
130
|
-
| `NEXT_PUBLIC_GSC_VERIFICATION` | Google Search Console verification code |
|
|
131
|
-
| `NEXT_PUBLIC_HOTJAR_ID` | Hotjar Site ID |
|
|
132
|
-
| `NEXT_PUBLIC_CLARITY_ID` | Microsoft Clarity Project ID |
|
|
133
|
-
| `NEXT_PUBLIC_API_URL` / `API_URL` | Core API base URL (for `getAnalyticsConfig`) |
|
|
515
|
+
|---|---|
|
|
516
|
+
| `NEXT_PUBLIC_ANALYTICS_WRITE_KEY` | Analytics provider write key (client-side) |
|
|
517
|
+
| `ANALYTICS_WRITE_KEY` | Analytics provider write key (server-side) |
|
|
134
518
|
|
|
135
519
|
---
|
|
136
520
|
|
|
137
|
-
##
|
|
521
|
+
## Compatibility Matrix
|
|
522
|
+
|
|
523
|
+
| Environment | Supported | Notes |
|
|
524
|
+
|---|---|---|
|
|
525
|
+
| React 18.x | ✅ | Full support |
|
|
526
|
+
| React 19.x | ✅ | Full support — no deprecated APIs used |
|
|
527
|
+
| Next.js 14 (App Router) | ✅ | Client + server tracking |
|
|
528
|
+
| Next.js 14 (Pages Router) | ✅ | Client tracking |
|
|
529
|
+
| Next.js 15 | ✅ | Full support |
|
|
530
|
+
| Vite (React) | ✅ | Client tracking |
|
|
531
|
+
| Remix | ✅ | Client tracking; use server utilities in loaders/actions |
|
|
532
|
+
| Node.js 18.x | ✅ | Server-side tracking |
|
|
533
|
+
| Node.js 20.x | ✅ | Server-side tracking (recommended) |
|
|
534
|
+
| Edge Runtime | ✅ | Server-side utilities work in edge functions |
|
|
535
|
+
| TypeScript 4.x | ✅ | Minimum supported |
|
|
536
|
+
| TypeScript 5.x | ✅ | Recommended |
|
|
537
|
+
| SSR | ✅ | Server utilities designed for SSR |
|
|
538
|
+
| CJS | ✅ | CommonJS supported |
|
|
539
|
+
| ESM | ✅ | ES modules supported |
|
|
138
540
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
AnalyticsConfig // TypeScript interface for the config shape
|
|
145
|
-
```
|
|
541
|
+
---
|
|
542
|
+
|
|
543
|
+
## License
|
|
544
|
+
|
|
545
|
+
MIT © CodeSwayam
|