@power-seo/tracking 1.0.0 → 1.0.1
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 +405 -384
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/react.cjs.map +1 -1
- package/dist/react.js.map +1 -1
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,384 +1,405 @@
|
|
|
1
|
-
# @power-seo/tracking — Analytics Script Builders & GDPR Consent Management for GA4, Clarity, PostHog, Plausible & Fathom
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@power-seo/tracking)
|
|
4
|
-
[](https://www.npmjs.com/package/@power-seo/tracking)
|
|
5
|
-
[](https://opensource.org/licenses/MIT)
|
|
6
|
-
[](https://www.typescriptlang.org/)
|
|
7
|
-
[](https://bundlephobia.com/package/@power-seo/tracking)
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## Overview
|
|
12
|
-
|
|
13
|
-
**@power-seo/tracking** is a consent-aware analytics toolkit for TypeScript that helps you manage GDPR-compliant script loading, define consent state, and query analytics APIs for GA4, Microsoft Clarity, PostHog, Plausible, and Fathom — all without runtime dependencies.
|
|
14
|
-
|
|
15
|
-
**What it does**
|
|
16
|
-
|
|
17
|
-
- ✅ **
|
|
18
|
-
- ✅ **Consent
|
|
19
|
-
- ✅ **
|
|
20
|
-
- ✅ **
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
**
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
**
|
|
39
|
-
- **
|
|
40
|
-
- **
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
- **
|
|
53
|
-
- **
|
|
54
|
-
- **
|
|
55
|
-
- **
|
|
56
|
-
- **
|
|
57
|
-
- **
|
|
58
|
-
- **
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
consent
|
|
96
|
-
const
|
|
97
|
-
//
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
-
|
|
133
|
-
-
|
|
134
|
-
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
- **
|
|
141
|
-
- **
|
|
142
|
-
- **
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
-
|
|
170
|
-
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
**
|
|
180
|
-
- **
|
|
181
|
-
- **
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
|
210
|
-
|
|
211
|
-
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
|
220
|
-
|
|
|
221
|
-
| [`@power-seo/
|
|
222
|
-
| [`@power-seo/
|
|
223
|
-
| [`@power-seo/
|
|
224
|
-
| [`@power-seo/
|
|
225
|
-
| [`@power-seo/
|
|
226
|
-
| [`@power-seo/
|
|
227
|
-
| [`@power-seo/
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
|
232
|
-
|
|
233
|
-
|
|
|
234
|
-
|
|
|
235
|
-
|
|
|
236
|
-
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
**
|
|
253
|
-
|
|
254
|
-
-
|
|
255
|
-
-
|
|
256
|
-
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
|
305
|
-
|
|
|
306
|
-
| `
|
|
307
|
-
| `
|
|
308
|
-
| `
|
|
309
|
-
| `
|
|
310
|
-
|
|
311
|
-
###
|
|
312
|
-
|
|
313
|
-
```ts
|
|
314
|
-
function
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
}
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
1
|
+
# @power-seo/tracking — Analytics Script Builders & GDPR Consent Management for GA4, Clarity, PostHog, Plausible & Fathom
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@power-seo/tracking)
|
|
4
|
+
[](https://www.npmjs.com/package/@power-seo/tracking)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](https://www.typescriptlang.org/)
|
|
7
|
+
[](https://bundlephobia.com/package/@power-seo/tracking)
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
**@power-seo/tracking** is a consent-aware analytics toolkit for TypeScript that helps you manage GDPR-compliant script loading, define consent state, and query analytics APIs for GA4, Microsoft Clarity, PostHog, Plausible, and Fathom — all without runtime dependencies.
|
|
14
|
+
|
|
15
|
+
**What it does**
|
|
16
|
+
|
|
17
|
+
- ✅ **Script builders for 5 platforms** — `buildGA4Script`, `buildClarityScript`, `buildPostHogScript`, `buildPlausibleScript`, `buildFathomScript`
|
|
18
|
+
- ✅ **Consent-aware loading** — every `ScriptConfig` exposes `shouldLoad(consentState)` to prevent loading without consent
|
|
19
|
+
- ✅ **Consent manager** — `createConsentManager()` with `grant()`, `revoke()`, `grantAll()`, `revokeAll()`, `onChange()`
|
|
20
|
+
- ✅ **React components** — `<AnalyticsScript>` and `<ConsentBanner>` for drop-in GDPR banner integration
|
|
21
|
+
- ✅ **Analytics API clients** — query GA4, Clarity, PostHog, Plausible, and Fathom data programmatically
|
|
22
|
+
|
|
23
|
+
**What it is not**
|
|
24
|
+
|
|
25
|
+
- ❌ **Not a Tag Manager** — does not replace Google Tag Manager; it is a code-first alternative
|
|
26
|
+
- ❌ **Not a legal compliance tool** — provides the technical mechanism; legal GDPR compliance requires proper privacy policy and DPA
|
|
27
|
+
|
|
28
|
+
**Recommended for**
|
|
29
|
+
|
|
30
|
+
- **Next.js App Router and Pages Router apps**, **Remix applications**, **SaaS products needing GDPR compliance**, and **analytics reporting dashboards**
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Why @power-seo/tracking Matters
|
|
35
|
+
|
|
36
|
+
**The problem**
|
|
37
|
+
|
|
38
|
+
- **Analytics scripts load before consent** — most analytics integrations don't check consent state before injecting `<script>` tags, violating GDPR
|
|
39
|
+
- **5 different provider APIs** — each analytics platform has different initialization code, configuration, and loading strategy
|
|
40
|
+
- **Consent state is UI state** — analytics loading needs to react to user consent choices in real time
|
|
41
|
+
|
|
42
|
+
**Why developers care**
|
|
43
|
+
|
|
44
|
+
- **Compliance:** GDPR requires analytics scripts not to load until the user grants consent
|
|
45
|
+
- **Performance:** Consent-gated loading prevents unnecessary scripts from affecting LCP and TTI before user interaction
|
|
46
|
+
- **UX:** A unified consent manager drives the consent banner, script loading, and API data fetching from one source of truth
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Key Features
|
|
51
|
+
|
|
52
|
+
- **Script builders for 5 platforms** — GA4 (2 script tags), Microsoft Clarity, PostHog, Plausible, and Fathom Analytics
|
|
53
|
+
- **Consent-aware loading** — every `ScriptConfig` exposes `shouldLoad(consentState)` — never loads a tracker without the right consent category
|
|
54
|
+
- **Consent manager** — `createConsentManager()` returns a typed store with `grant()`, `revoke()`, `grantAll()`, `revokeAll()`, `getState()`, and `onChange()` subscription
|
|
55
|
+
- **GDPR-friendly defaults** — `necessary` consent is always `true` and cannot be revoked; `analytics`, `marketing`, `preferences` default to `false`
|
|
56
|
+
- **React components** — `<AnalyticsScript>` renders only consented scripts; `<ConsentBanner>` is a ready-to-use GDPR banner
|
|
57
|
+
- **GA4 Data API client** — `createGA4Client()` queries reports, real-time data, and metadata
|
|
58
|
+
- **Clarity API client** — `createClarityClient()` fetches projects, session insights, and heatmap data
|
|
59
|
+
- **PostHog API client** — `createPostHogClient()` queries events, trends, funnels, and persons
|
|
60
|
+
- **Plausible Stats API client** — `createPlausibleClient()` fetches timeseries, breakdowns, and aggregate stats
|
|
61
|
+
- **Fathom API client** — `createFathomClient()` fetches sites, pageviews, and referrer data
|
|
62
|
+
- **Zero runtime dependencies** — pure TypeScript with optional React peer dependency
|
|
63
|
+
- **Full TypeScript support** — typed config interfaces, consent state, and response shapes for every provider
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Benefits of Using @power-seo/tracking
|
|
68
|
+
|
|
69
|
+
- **GDPR compliance**: `shouldLoad(consent)` guarantees scripts only load when the correct consent category is granted
|
|
70
|
+
- **Simpler integration**: One consent manager drives the consent banner UI, script loading, and API access — no fragmented state
|
|
71
|
+
- **Better performance**: Analytics scripts with `lazyOnload` strategy don't block page render
|
|
72
|
+
- **Faster delivery**: Typed script builders for 5 providers eliminate provider-specific documentation research
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Quick Start
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
import { createConsentManager, buildGA4Script, buildPlausibleScript } from '@power-seo/tracking';
|
|
80
|
+
|
|
81
|
+
// 1. Create consent manager — analytics off by default
|
|
82
|
+
const consent = createConsentManager({
|
|
83
|
+
necessary: true,
|
|
84
|
+
analytics: false,
|
|
85
|
+
marketing: false,
|
|
86
|
+
preferences: false,
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
// 2. Build script configs
|
|
90
|
+
const scripts = [
|
|
91
|
+
...buildGA4Script({ measurementId: 'G-XXXXXXX' }),
|
|
92
|
+
buildPlausibleScript({ domain: 'example.com' }),
|
|
93
|
+
];
|
|
94
|
+
|
|
95
|
+
// 3. Only load scripts where consent matches
|
|
96
|
+
const toLoad = scripts.filter((s) => s.shouldLoad(consent.getState()));
|
|
97
|
+
// toLoad → [] until analytics consent is granted
|
|
98
|
+
|
|
99
|
+
// 4. Grant consent (e.g. after user clicks "Accept All")
|
|
100
|
+
consent.grantAll();
|
|
101
|
+
const nowToLoad = scripts.filter((s) => s.shouldLoad(consent.getState()));
|
|
102
|
+
// nowToLoad → [GA4Script1, GA4Script2, PlausibleScript]
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
**What you should see**
|
|
106
|
+
|
|
107
|
+
- Zero scripts loaded until `consent.grantAll()` is called
|
|
108
|
+
- Scripts filtered by `shouldLoad(consentState)` — no analytics without user approval
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Installation
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npm i @power-seo/tracking
|
|
116
|
+
# or
|
|
117
|
+
yarn add @power-seo/tracking
|
|
118
|
+
# or
|
|
119
|
+
pnpm add @power-seo/tracking
|
|
120
|
+
# or
|
|
121
|
+
bun add @power-seo/tracking
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
For React components, React 18+ is required as a peer dependency.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Framework Compatibility
|
|
129
|
+
|
|
130
|
+
**Supported**
|
|
131
|
+
|
|
132
|
+
- ✅ Next.js App Router — use `<AnalyticsScript>` and `<ConsentBanner>` in root layout
|
|
133
|
+
- ✅ Next.js Pages Router — use in `_app.tsx`
|
|
134
|
+
- ✅ Remix — use in root route component
|
|
135
|
+
- ✅ Node.js 18+ — API clients for server-side analytics data fetching
|
|
136
|
+
- ✅ Vite + React — works in standard SPA setup
|
|
137
|
+
|
|
138
|
+
**Environment notes**
|
|
139
|
+
|
|
140
|
+
- **SSR/SSG:** Script builders and consent manager are SSR-safe; React components require client-side rendering for DOM injection
|
|
141
|
+
- **Edge runtime:** Script builders and consent manager are edge-compatible; API clients require Node.js fetch
|
|
142
|
+
- **Browser-only usage:** `shouldLoad()` and consent manager work in browser environments
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Use Cases
|
|
147
|
+
|
|
148
|
+
- **GDPR-compliant web apps** — load analytics scripts only after user consent
|
|
149
|
+
- **SaaS marketing sites** — track user behavior with GA4 while respecting privacy regulations
|
|
150
|
+
- **E-commerce stores** — Clarity session recordings for UX optimization with consent gate
|
|
151
|
+
- **Multi-provider analytics** — run GA4 + Plausible + PostHog side-by-side for data validation
|
|
152
|
+
- **Privacy-first apps** — Plausible or Fathom as cookieless, GDPR-compliant alternatives to GA4
|
|
153
|
+
- **Analytics dashboards** — query GA4, Plausible, or Fathom APIs for custom reporting
|
|
154
|
+
- **A/B testing pipelines** — PostHog feature flags + event tracking with consent management
|
|
155
|
+
- **Enterprise compliance** — full audit trail of when consent was granted per category
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Example (Before / After)
|
|
160
|
+
|
|
161
|
+
```text
|
|
162
|
+
Before:
|
|
163
|
+
- GA4 script injected in <head> unconditionally → violates GDPR before consent
|
|
164
|
+
- 3 separate analytics integrations with different initialization patterns
|
|
165
|
+
- Consent banner only hides scripts after first render → tracking still fires
|
|
166
|
+
|
|
167
|
+
After (@power-seo/tracking):
|
|
168
|
+
- buildGA4Script({ measurementId }) → ScriptConfig with shouldLoad(consent)
|
|
169
|
+
- createConsentManager({ analytics: false }) → analytics = false until user clicks Accept
|
|
170
|
+
- <AnalyticsScript scripts={scripts} consent={consent} /> → renders nothing until consented
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Implementation Best Practices
|
|
176
|
+
|
|
177
|
+
- **Set `analytics: false` by default** in `createConsentManager()` — GDPR requires opt-in, not opt-out
|
|
178
|
+
- **Persist consent state** to `localStorage` or a cookie — re-read on page load to avoid showing the banner twice
|
|
179
|
+
- **Use `onChange()`** to reactively reload scripts after consent is granted
|
|
180
|
+
- **Do not load GA4 or Clarity** without `analytics` consent — these are tracking, not `necessary` scripts
|
|
181
|
+
- **Include a working privacy policy link** in `<ConsentBanner privacyPolicyUrl="/privacy-policy" />`
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## Architecture Overview
|
|
186
|
+
|
|
187
|
+
**Where it runs**
|
|
188
|
+
|
|
189
|
+
- **Build-time**: Script builder configs are defined server-side; passed to client as serialized props
|
|
190
|
+
- **Runtime**: Consent manager runs client-side; `shouldLoad()` is evaluated on consent change
|
|
191
|
+
- **CI/CD**: API clients run server-side for scheduled analytics data fetching and reporting
|
|
192
|
+
|
|
193
|
+
**Data flow**
|
|
194
|
+
|
|
195
|
+
1. **Input**: Provider credentials (measurementId, projectId), initial consent state
|
|
196
|
+
2. **Analysis**: `shouldLoad(consentState)` evaluates per-script consent requirements
|
|
197
|
+
3. **Output**: Filtered `ScriptConfig[]` injected into `<head>` as `<script>` tags
|
|
198
|
+
4. **Action**: Analytics providers receive tracking data only when consent is granted
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## Features Comparison with Popular Packages
|
|
203
|
+
|
|
204
|
+
| Capability | @next/third-parties | partytown | cookiebot | @power-seo/tracking |
|
|
205
|
+
| ---------------------------- | ------------------: | --------: | --------: | ------------------: |
|
|
206
|
+
| Typed script builders | ❌ | ❌ | ❌ | ✅ |
|
|
207
|
+
| Consent-aware `shouldLoad()` | ❌ | ❌ | ✅ | ✅ |
|
|
208
|
+
| Built-in consent manager | ❌ | ❌ | ✅ (paid) | ✅ |
|
|
209
|
+
| Analytics API clients | ❌ | ❌ | ❌ | ✅ |
|
|
210
|
+
| 5-provider support | ⚠️ | ⚠️ | ✅ | ✅ |
|
|
211
|
+
| Zero runtime dependencies | ✅ | ✅ | ❌ | ✅ |
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
## @power-seo Ecosystem
|
|
216
|
+
|
|
217
|
+
All 17 packages are independently installable — use only what you need.
|
|
218
|
+
|
|
219
|
+
| Package | Install | Description |
|
|
220
|
+
| ------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------- |
|
|
221
|
+
| [`@power-seo/core`](https://www.npmjs.com/package/@power-seo/core) | `npm i @power-seo/core` | Framework-agnostic utilities, types, validators, and constants |
|
|
222
|
+
| [`@power-seo/react`](https://www.npmjs.com/package/@power-seo/react) | `npm i @power-seo/react` | React SEO components — meta, Open Graph, Twitter Card, breadcrumbs |
|
|
223
|
+
| [`@power-seo/meta`](https://www.npmjs.com/package/@power-seo/meta) | `npm i @power-seo/meta` | SSR meta helpers for Next.js App Router, Remix v2, and generic SSR |
|
|
224
|
+
| [`@power-seo/schema`](https://www.npmjs.com/package/@power-seo/schema) | `npm i @power-seo/schema` | Type-safe JSON-LD structured data — 20 builders + 18 React components |
|
|
225
|
+
| [`@power-seo/content-analysis`](https://www.npmjs.com/package/@power-seo/content-analysis) | `npm i @power-seo/content-analysis` | Yoast-style SEO content scoring engine with React components |
|
|
226
|
+
| [`@power-seo/readability`](https://www.npmjs.com/package/@power-seo/readability) | `npm i @power-seo/readability` | Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI |
|
|
227
|
+
| [`@power-seo/preview`](https://www.npmjs.com/package/@power-seo/preview) | `npm i @power-seo/preview` | SERP, Open Graph, and Twitter/X Card preview generators |
|
|
228
|
+
| [`@power-seo/sitemap`](https://www.npmjs.com/package/@power-seo/sitemap) | `npm i @power-seo/sitemap` | XML sitemap generation, streaming, index splitting, and validation |
|
|
229
|
+
| [`@power-seo/redirects`](https://www.npmjs.com/package/@power-seo/redirects) | `npm i @power-seo/redirects` | Redirect engine with Next.js, Remix, and Express adapters |
|
|
230
|
+
| [`@power-seo/links`](https://www.npmjs.com/package/@power-seo/links) | `npm i @power-seo/links` | Link graph analysis — orphan detection, suggestions, equity scoring |
|
|
231
|
+
| [`@power-seo/audit`](https://www.npmjs.com/package/@power-seo/audit) | `npm i @power-seo/audit` | Full SEO audit engine — meta, content, structure, performance rules |
|
|
232
|
+
| [`@power-seo/images`](https://www.npmjs.com/package/@power-seo/images) | `npm i @power-seo/images` | Image SEO — alt text, lazy loading, format analysis, image sitemaps |
|
|
233
|
+
| [`@power-seo/ai`](https://www.npmjs.com/package/@power-seo/ai) | `npm i @power-seo/ai` | LLM-agnostic AI prompt templates and parsers for SEO tasks |
|
|
234
|
+
| [`@power-seo/analytics`](https://www.npmjs.com/package/@power-seo/analytics) | `npm i @power-seo/analytics` | Merge GSC + audit data, trend analysis, ranking insights, dashboard |
|
|
235
|
+
| [`@power-seo/search-console`](https://www.npmjs.com/package/@power-seo/search-console) | `npm i @power-seo/search-console` | Google Search Console API — OAuth2, service account, URL inspection |
|
|
236
|
+
| [`@power-seo/integrations`](https://www.npmjs.com/package/@power-seo/integrations) | `npm i @power-seo/integrations` | Semrush and Ahrefs API clients with rate limiting and pagination |
|
|
237
|
+
| [`@power-seo/tracking`](https://www.npmjs.com/package/@power-seo/tracking) | `npm i @power-seo/tracking` | GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management |
|
|
238
|
+
|
|
239
|
+
### Ecosystem vs alternatives
|
|
240
|
+
|
|
241
|
+
| Need | Common approach | @power-seo approach |
|
|
242
|
+
| ----------------------- | ------------------------- | ---------------------------------------------------- |
|
|
243
|
+
| Analytics scripts | Direct `<script>` in HTML | `@power-seo/tracking` — consent-gated `ScriptConfig` |
|
|
244
|
+
| GDPR consent banner | Cookiebot (paid) | `@power-seo/tracking` — built-in `<ConsentBanner>` |
|
|
245
|
+
| GSC data queries | `googleapis` | `@power-seo/search-console` — typed, auto-paginated |
|
|
246
|
+
| SEO analytics dashboard | Looker Studio | `@power-seo/analytics` — merge GSC + audit data |
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## Enterprise Integration
|
|
251
|
+
|
|
252
|
+
**Multi-tenant SaaS**
|
|
253
|
+
|
|
254
|
+
- **Per-tenant analytics**: Each tenant supplies their own `measurementId`; instantiate separate `ScriptConfig` per tenant
|
|
255
|
+
- **Consent per tenant**: Persist consent state in tenant-scoped cookies or DB; initialize `createConsentManager()` from stored state
|
|
256
|
+
- **Data isolation**: API clients are instantiated per tenant — no cross-tenant data leakage
|
|
257
|
+
|
|
258
|
+
**ERP / internal portals**
|
|
259
|
+
|
|
260
|
+
- Load Clarity session recordings only on public-facing pages, not authenticated internal routes
|
|
261
|
+
- Use PostHog feature flags + event tracking for internal user behavior analytics with explicit consent
|
|
262
|
+
- Build custom analytics reports with `createGA4Client()` or `createPlausibleClient()` for stakeholder dashboards
|
|
263
|
+
|
|
264
|
+
**Recommended integration pattern**
|
|
265
|
+
|
|
266
|
+
- Store consent state in **`localStorage`** or **HTTP-only cookie**
|
|
267
|
+
- Initialize `createConsentManager()` from stored state on every page load
|
|
268
|
+
- Trigger `onChange()` to reload scripts reactively when user updates consent preferences
|
|
269
|
+
- Export consent events to **audit logs** for compliance documentation
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## Scope and Limitations
|
|
274
|
+
|
|
275
|
+
**This package does**
|
|
276
|
+
|
|
277
|
+
- ✅ Build consent-aware script configs for 5 analytics platforms
|
|
278
|
+
- ✅ Manage GDPR consent state with typed store and reactive subscriptions
|
|
279
|
+
- ✅ Render consent-gated script tags and GDPR banner via React components
|
|
280
|
+
- ✅ Query analytics data programmatically via 5 provider API clients
|
|
281
|
+
|
|
282
|
+
**This package does not**
|
|
283
|
+
|
|
284
|
+
- ❌ Replace a full consent management platform (CMP) for complex legal requirements
|
|
285
|
+
- ❌ Implement consent record-keeping or proof-of-consent storage — handle this in your backend
|
|
286
|
+
- ❌ Block server-side tracking (cookies set by CDN or server) — client-side only
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
## API Reference
|
|
291
|
+
|
|
292
|
+
### Script Builders
|
|
293
|
+
|
|
294
|
+
| Function | Config Props | Returns | Description |
|
|
295
|
+
| ---------------------- | --------------------------- | ---------------- | ---------------------------------- |
|
|
296
|
+
| `buildGA4Script` | `{ measurementId }` | `ScriptConfig[]` | Google Analytics 4 (2 script tags) |
|
|
297
|
+
| `buildClarityScript` | `{ projectId }` | `ScriptConfig` | Microsoft Clarity |
|
|
298
|
+
| `buildPostHogScript` | `{ apiKey, apiHost? }` | `ScriptConfig` | PostHog |
|
|
299
|
+
| `buildPlausibleScript` | `{ domain, customDomain? }` | `ScriptConfig` | Plausible Analytics |
|
|
300
|
+
| `buildFathomScript` | `{ siteId }` | `ScriptConfig` | Fathom Analytics |
|
|
301
|
+
|
|
302
|
+
#### `ScriptConfig`
|
|
303
|
+
|
|
304
|
+
| Prop | Type | Description |
|
|
305
|
+
| -------------- | ----------------------------------------------------------- | -------------------------------------- |
|
|
306
|
+
| `src` | `string \| undefined` | External script URL |
|
|
307
|
+
| `inlineScript` | `string \| undefined` | Inline JavaScript content |
|
|
308
|
+
| `strategy` | `'beforeInteractive' \| 'afterInteractive' \| 'lazyOnload'` | Loading strategy hint |
|
|
309
|
+
| `shouldLoad` | `(consent: ConsentState) => boolean` | Returns `true` if this script may load |
|
|
310
|
+
|
|
311
|
+
### Consent Manager
|
|
312
|
+
|
|
313
|
+
```ts
|
|
314
|
+
function createConsentManager(initialState: Partial<ConsentState>): ConsentManager;
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
| Method | Signature | Description |
|
|
318
|
+
| ----------- | ------------------------------------------- | ----------------------------------------- |
|
|
319
|
+
| `grant` | `(category: ConsentCategory) => void` | Grant a consent category |
|
|
320
|
+
| `revoke` | `(category: ConsentCategory) => void` | Revoke a consent category |
|
|
321
|
+
| `grantAll` | `() => void` | Grant all non-necessary categories |
|
|
322
|
+
| `revokeAll` | `() => void` | Revoke all non-necessary categories |
|
|
323
|
+
| `getState` | `() => ConsentState` | Get the current consent snapshot |
|
|
324
|
+
| `onChange` | `(cb: ConsentChangeCallback) => () => void` | Subscribe to changes; returns unsubscribe |
|
|
325
|
+
|
|
326
|
+
### API Clients
|
|
327
|
+
|
|
328
|
+
```ts
|
|
329
|
+
function createGA4Client(config: GA4Config): GA4Client;
|
|
330
|
+
function createClarityClient(config: ClarityConfig): ClarityClient;
|
|
331
|
+
function createPostHogClient(config: PostHogConfig): PostHogClient;
|
|
332
|
+
function createPlausibleClient(config: PlausibleConfig): PlausibleClient;
|
|
333
|
+
function createFathomClient(config: FathomConfig): FathomClient;
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### React Components
|
|
337
|
+
|
|
338
|
+
| Component | Props | Description |
|
|
339
|
+
| ------------------- | -------------------------------------------------------- | ------------------------------------------------------- |
|
|
340
|
+
| `<AnalyticsScript>` | `{ scripts: ScriptConfig[], consent: ConsentState }` | Renders `<script>` tags that pass `shouldLoad(consent)` |
|
|
341
|
+
| `<ConsentBanner>` | `{ manager: ConsentManager, privacyPolicyUrl?: string }` | GDPR cookie consent banner with Accept All / Reject All |
|
|
342
|
+
|
|
343
|
+
### Types
|
|
344
|
+
|
|
345
|
+
```ts
|
|
346
|
+
import type {
|
|
347
|
+
ConsentCategory, // 'necessary' | 'analytics' | 'marketing' | 'preferences'
|
|
348
|
+
ConsentState, // { necessary, analytics, marketing, preferences }
|
|
349
|
+
ConsentManager,
|
|
350
|
+
ScriptConfig,
|
|
351
|
+
GA4Config,
|
|
352
|
+
GA4Client,
|
|
353
|
+
ClarityConfig,
|
|
354
|
+
ClarityClient,
|
|
355
|
+
PostHogConfig,
|
|
356
|
+
PostHogClient,
|
|
357
|
+
PlausibleConfig,
|
|
358
|
+
PlausibleClient,
|
|
359
|
+
FathomConfig,
|
|
360
|
+
FathomClient,
|
|
361
|
+
} from '@power-seo/tracking';
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## Contributing
|
|
367
|
+
|
|
368
|
+
- Issues: [github.com/cybercraftbd/power-seo/issues](https://github.com/cybercraftbd/power-seo/issues)
|
|
369
|
+
- PRs: [github.com/cybercraftbd/power-seo/pulls](https://github.com/cybercraftbd/power-seo/pulls)
|
|
370
|
+
- Development setup:
|
|
371
|
+
1. `pnpm i`
|
|
372
|
+
2. `pnpm build`
|
|
373
|
+
3. `pnpm test`
|
|
374
|
+
|
|
375
|
+
**Release workflow**
|
|
376
|
+
|
|
377
|
+
- `npm version patch|minor|major`
|
|
378
|
+
- `npm publish --access public`
|
|
379
|
+
|
|
380
|
+
---
|
|
381
|
+
|
|
382
|
+
## About CyberCraft Bangladesh
|
|
383
|
+
|
|
384
|
+
**CyberCraft Bangladesh** is a Bangladesh-based enterprise-grade software engineering company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.
|
|
385
|
+
|
|
386
|
+
| | |
|
|
387
|
+
| -------------------- | -------------------------------------------------------------- |
|
|
388
|
+
| **Website** | [ccbd.dev](https://ccbd.dev) |
|
|
389
|
+
| **GitHub** | [github.com/cybercraftbd](https://github.com/cybercraftbd) |
|
|
390
|
+
| **npm Organization** | [npmjs.com/org/power-seo](https://www.npmjs.com/org/power-seo) |
|
|
391
|
+
| **Email** | [info@ccbd.dev](mailto:info@ccbd.dev) |
|
|
392
|
+
|
|
393
|
+
---
|
|
394
|
+
|
|
395
|
+
## License
|
|
396
|
+
|
|
397
|
+
**MIT**
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
## Keywords
|
|
402
|
+
|
|
403
|
+
```text
|
|
404
|
+
analytics, ga4, google-analytics, microsoft-clarity, posthog, plausible, fathom, gdpr, consent-management, cookie-consent, typescript, react, nextjs, privacy
|
|
405
|
+
```
|