@power-seo/tracking 1.0.2 → 1.0.10
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/LICENSE +21 -0
- package/README.md +247 -246
- package/dist/index.cjs +49 -14
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +13 -3
- package/dist/index.js.map +1 -1
- package/dist/react.cjs +45 -22
- package/dist/react.cjs.map +1 -1
- package/dist/react.js +5 -5
- package/dist/react.js.map +1 -1
- package/package.json +22 -14
package/README.md
CHANGED
|
@@ -1,75 +1,91 @@
|
|
|
1
|
-
# @power-seo/tracking
|
|
1
|
+
# @power-seo/tracking
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
Consent-aware analytics script builders and GDPR consent management for TypeScript — GA4, Microsoft Clarity, PostHog, Plausible, and Fathom with a unified `shouldLoad(consentState)` API and React components.
|
|
2
6
|
|
|
3
7
|
[](https://www.npmjs.com/package/@power-seo/tracking)
|
|
4
8
|
[](https://www.npmjs.com/package/@power-seo/tracking)
|
|
9
|
+
[](https://socket.dev/npm/package/@power-seo/tracking)
|
|
10
|
+
[](https://github.com/CyberCraftBD/power-seo/actions)
|
|
5
11
|
[](https://opensource.org/licenses/MIT)
|
|
6
12
|
[](https://www.typescriptlang.org/)
|
|
7
13
|
[](https://bundlephobia.com/package/@power-seo/tracking)
|
|
8
14
|
|
|
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**
|
|
15
|
+
`@power-seo/tracking` is a consent-aware analytics toolkit for TypeScript. Build typed script configs for five analytics platforms, manage GDPR consent state with a reactive store, and render consent-gated script tags and a cookie banner via drop-in React components. Every `ScriptConfig` exposes `shouldLoad(consentState)` — scripts never load without the correct consent category. The consent manager defaults to `necessary: true` and all other categories to `false`, satisfying GDPR opt-in requirements out of the box. Five typed API clients let you query GA4, Clarity, PostHog, Plausible, and Fathom data server-side for custom reporting and dashboards.
|
|
29
16
|
|
|
30
|
-
|
|
17
|
+
> **Zero runtime dependencies** — pure TypeScript with an optional React 18+ peer dependency for the `<AnalyticsScript>` and `<ConsentBanner>` components.
|
|
31
18
|
|
|
32
19
|
---
|
|
33
20
|
|
|
34
|
-
## Why @power-seo/tracking
|
|
21
|
+
## Why @power-seo/tracking?
|
|
35
22
|
|
|
36
|
-
|
|
23
|
+
| | Without | With |
|
|
24
|
+
| ----------------- | ---------------------------------------------- | --------------------------------------------------------- |
|
|
25
|
+
| GDPR consent | ❌ Scripts load unconditionally in `<head>` | ✅ `shouldLoad(consentState)` gates every script |
|
|
26
|
+
| Consent manager | ❌ Custom UI state per project | ✅ `createConsentManager()` with typed categories |
|
|
27
|
+
| Multi-provider | ❌ Different init code per analytics platform | ✅ One API for GA4, Clarity, PostHog, Plausible, Fathom |
|
|
28
|
+
| React integration | ❌ Manual `<script>` injection in layout | ✅ `<AnalyticsScript>` and `<ConsentBanner>` drop-in |
|
|
29
|
+
| API data access | ❌ Platform-specific SDK research per provider | ✅ Typed clients for all 5 providers |
|
|
30
|
+
| Performance | ❌ Scripts block LCP before user interaction | ✅ Lazy loading strategy prevents render blocking |
|
|
31
|
+
| TypeScript | ❌ Loose config objects with no type checking | ✅ Typed `ScriptConfig`, `ConsentState`, `ConsentManager` |
|
|
37
32
|
|
|
38
|
-
|
|
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
|
|
33
|
+
|
|
47
34
|
|
|
48
35
|
---
|
|
49
36
|
|
|
50
|
-
##
|
|
37
|
+
## Features
|
|
51
38
|
|
|
52
|
-
- **Script builders for 5 platforms** —
|
|
53
|
-
- **Consent-aware loading** — every `ScriptConfig` exposes `shouldLoad(consentState)` — never
|
|
39
|
+
- **Script builders for 5 platforms** — `buildGA4Script` (2 script tags), `buildClarityScript`, `buildPostHogScript`, `buildPlausibleScript`, `buildFathomScript`
|
|
40
|
+
- **Consent-aware loading** — every `ScriptConfig` exposes `shouldLoad(consentState)` — scripts never load without the right consent category
|
|
54
41
|
- **Consent manager** — `createConsentManager()` returns a typed store with `grant()`, `revoke()`, `grantAll()`, `revokeAll()`, `getState()`, and `onChange()` subscription
|
|
55
42
|
- **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
|
|
43
|
+
- **React components** — `<AnalyticsScript>` renders only consented scripts; `<ConsentBanner>` is a ready-to-use GDPR cookie banner
|
|
57
44
|
- **GA4 Data API client** — `createGA4Client()` queries reports, real-time data, and metadata
|
|
58
45
|
- **Clarity API client** — `createClarityClient()` fetches projects, session insights, and heatmap data
|
|
59
46
|
- **PostHog API client** — `createPostHogClient()` queries events, trends, funnels, and persons
|
|
60
47
|
- **Plausible Stats API client** — `createPlausibleClient()` fetches timeseries, breakdowns, and aggregate stats
|
|
61
48
|
- **Fathom API client** — `createFathomClient()` fetches sites, pageviews, and referrer data
|
|
62
|
-
- **
|
|
49
|
+
- **Framework-agnostic** — script builders and consent manager work in Next.js, Remix, Vite, Vanilla JS, and Edge runtimes
|
|
63
50
|
- **Full TypeScript support** — typed config interfaces, consent state, and response shapes for every provider
|
|
51
|
+
- **Tree-shakeable** — import only the providers you use; zero dead code in your bundle
|
|
52
|
+
|
|
53
|
+
|
|
64
54
|
|
|
65
55
|
---
|
|
66
56
|
|
|
67
|
-
##
|
|
57
|
+
## Comparison
|
|
58
|
+
|
|
59
|
+
| Feature | @next/third-parties | partytown | cookiebot | @power-seo/tracking |
|
|
60
|
+
| ---------------------------- | :-----------------: | :-------: | :-------: | :-----------------: |
|
|
61
|
+
| Typed script builders | ❌ | ❌ | ❌ | ✅ |
|
|
62
|
+
| Consent-aware `shouldLoad()` | ❌ | ❌ | ✅ | ✅ |
|
|
63
|
+
| Built-in consent manager | ❌ | ❌ | ✅ (paid) | ✅ |
|
|
64
|
+
| Analytics API clients | ❌ | ❌ | ❌ | ✅ |
|
|
65
|
+
| 5-provider support | ⚠️ | ⚠️ | ✅ | ✅ |
|
|
66
|
+
| Zero runtime dependencies | ✅ | ✅ | ❌ | ✅ |
|
|
67
|
+
| TypeScript-first | ❌ | ❌ | ❌ | ✅ |
|
|
68
|
+
| React components | ⚠️ | ❌ | ✅ | ✅ |
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## Installation
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npm install @power-seo/tracking
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
yarn add @power-seo/tracking
|
|
82
|
+
```
|
|
68
83
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
84
|
+
```bash
|
|
85
|
+
pnpm add @power-seo/tracking
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
For React components, React 18+ is required as a peer dependency.
|
|
73
89
|
|
|
74
90
|
---
|
|
75
91
|
|
|
@@ -78,7 +94,7 @@
|
|
|
78
94
|
```ts
|
|
79
95
|
import { createConsentManager, buildGA4Script, buildPlausibleScript } from '@power-seo/tracking';
|
|
80
96
|
|
|
81
|
-
// 1. Create consent manager — analytics off by default
|
|
97
|
+
// 1. Create consent manager — analytics off by default (GDPR opt-in)
|
|
82
98
|
const consent = createConsentManager({
|
|
83
99
|
necessary: true,
|
|
84
100
|
analytics: false,
|
|
@@ -86,7 +102,7 @@ const consent = createConsentManager({
|
|
|
86
102
|
preferences: false,
|
|
87
103
|
});
|
|
88
104
|
|
|
89
|
-
// 2. Build script configs
|
|
105
|
+
// 2. Build script configs for your providers
|
|
90
106
|
const scripts = [
|
|
91
107
|
...buildGA4Script({ measurementId: 'G-XXXXXXX' }),
|
|
92
108
|
buildPlausibleScript({ domain: 'example.com' }),
|
|
@@ -102,188 +118,139 @@ const nowToLoad = scripts.filter((s) => s.shouldLoad(consent.getState()));
|
|
|
102
118
|
// nowToLoad → [GA4Script1, GA4Script2, PlausibleScript]
|
|
103
119
|
```
|
|
104
120
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
- Zero scripts loaded until `consent.grantAll()` is called
|
|
108
|
-
- Scripts filtered by `shouldLoad(consentState)` — no analytics without user approval
|
|
121
|
+
|
|
109
122
|
|
|
110
123
|
---
|
|
111
124
|
|
|
112
|
-
##
|
|
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
|
-
```
|
|
125
|
+
## Usage
|
|
123
126
|
|
|
124
|
-
|
|
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)
|
|
127
|
+
### Script Builders
|
|
160
128
|
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
129
|
+
```ts
|
|
130
|
+
import {
|
|
131
|
+
buildGA4Script,
|
|
132
|
+
buildClarityScript,
|
|
133
|
+
buildPostHogScript,
|
|
134
|
+
buildPlausibleScript,
|
|
135
|
+
buildFathomScript,
|
|
136
|
+
} from '@power-seo/tracking';
|
|
166
137
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
138
|
+
const scripts = [
|
|
139
|
+
...buildGA4Script({ measurementId: 'G-XXXXXXX' }), // returns ScriptConfig[]
|
|
140
|
+
buildClarityScript({ projectId: 'abc123' }),
|
|
141
|
+
buildPostHogScript({ apiKey: 'phc_xxx', apiHost: 'https://app.posthog.com' }),
|
|
142
|
+
buildPlausibleScript({ domain: 'example.com' }),
|
|
143
|
+
buildFathomScript({ siteId: 'ABCDEFGH' }),
|
|
144
|
+
];
|
|
171
145
|
```
|
|
172
146
|
|
|
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
|
-
---
|
|
147
|
+
### Consent Manager
|
|
184
148
|
|
|
185
|
-
|
|
149
|
+
```ts
|
|
150
|
+
import { createConsentManager } from '@power-seo/tracking';
|
|
186
151
|
|
|
187
|
-
|
|
152
|
+
const consent = createConsentManager({ necessary: true, analytics: false });
|
|
188
153
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
154
|
+
// Grant/revoke individual categories
|
|
155
|
+
consent.grant('analytics');
|
|
156
|
+
consent.revoke('marketing');
|
|
192
157
|
|
|
193
|
-
|
|
158
|
+
// Grant or revoke all non-necessary categories
|
|
159
|
+
consent.grantAll();
|
|
160
|
+
consent.revokeAll();
|
|
194
161
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
4. **Action**: Analytics providers receive tracking data only when consent is granted
|
|
162
|
+
// Read current state
|
|
163
|
+
const state = consent.getState();
|
|
164
|
+
// { necessary: true, analytics: true, marketing: false, preferences: false }
|
|
199
165
|
|
|
200
|
-
|
|
166
|
+
// Subscribe to changes — returns unsubscribe function
|
|
167
|
+
const unsubscribe = consent.onChange((newState) => {
|
|
168
|
+
console.log('Consent changed:', newState);
|
|
169
|
+
});
|
|
170
|
+
```
|
|
201
171
|
|
|
202
|
-
|
|
172
|
+
### React — AnalyticsScript
|
|
203
173
|
|
|
204
|
-
|
|
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 | ✅ | ✅ | ❌ | ✅ |
|
|
174
|
+
```tsx
|
|
175
|
+
'use client';
|
|
212
176
|
|
|
213
|
-
|
|
177
|
+
import { AnalyticsScript } from '@power-seo/tracking/react';
|
|
178
|
+
import { buildGA4Script, createConsentManager } from '@power-seo/tracking';
|
|
214
179
|
|
|
215
|
-
|
|
180
|
+
const consent = createConsentManager({ necessary: true, analytics: false });
|
|
181
|
+
const scripts = buildGA4Script({ measurementId: 'G-XXXXXXX' });
|
|
216
182
|
|
|
217
|
-
|
|
183
|
+
export default function Layout({ children }: { children: React.ReactNode }) {
|
|
184
|
+
return (
|
|
185
|
+
<html>
|
|
186
|
+
<head>
|
|
187
|
+
<AnalyticsScript scripts={scripts} consent={consent.getState()} />
|
|
188
|
+
</head>
|
|
189
|
+
<body>{children}</body>
|
|
190
|
+
</html>
|
|
191
|
+
);
|
|
192
|
+
}
|
|
193
|
+
```
|
|
218
194
|
|
|
219
|
-
|
|
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 |
|
|
195
|
+
### React — ConsentBanner
|
|
238
196
|
|
|
239
|
-
|
|
197
|
+
```tsx
|
|
198
|
+
'use client';
|
|
240
199
|
|
|
241
|
-
|
|
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 |
|
|
200
|
+
import { ConsentBanner } from '@power-seo/tracking/react';
|
|
201
|
+
import { createConsentManager } from '@power-seo/tracking';
|
|
247
202
|
|
|
248
|
-
|
|
203
|
+
const consent = createConsentManager({ necessary: true, analytics: false });
|
|
249
204
|
|
|
250
|
-
|
|
205
|
+
export function CookieBanner() {
|
|
206
|
+
return <ConsentBanner manager={consent} privacyPolicyUrl="/privacy-policy" />;
|
|
207
|
+
}
|
|
208
|
+
```
|
|
251
209
|
|
|
252
|
-
|
|
210
|
+
### Analytics API Clients
|
|
253
211
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
- **Data isolation**: API clients are instantiated per tenant — no cross-tenant data leakage
|
|
212
|
+
```ts
|
|
213
|
+
import { createGA4Client, createPlausibleClient } from '@power-seo/tracking';
|
|
257
214
|
|
|
258
|
-
|
|
215
|
+
// Query GA4 reports
|
|
216
|
+
const ga4 = createGA4Client({
|
|
217
|
+
measurementId: 'G-XXXXXXX',
|
|
218
|
+
apiSecret: process.env.GA4_API_SECRET!,
|
|
219
|
+
});
|
|
259
220
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
221
|
+
// Query Plausible stats
|
|
222
|
+
const plausible = createPlausibleClient({
|
|
223
|
+
domain: 'example.com',
|
|
224
|
+
apiKey: process.env.PLAUSIBLE_API_KEY!,
|
|
225
|
+
});
|
|
263
226
|
|
|
264
|
-
|
|
227
|
+
const stats = await plausible.getAggregate({ period: '7d' });
|
|
228
|
+
console.log(stats.visitors, stats.pageviews);
|
|
229
|
+
```
|
|
265
230
|
|
|
266
|
-
|
|
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
|
|
231
|
+
### Reactive Consent Loading (Next.js App Router)
|
|
270
232
|
|
|
271
|
-
|
|
233
|
+
```tsx
|
|
234
|
+
'use client';
|
|
272
235
|
|
|
273
|
-
|
|
236
|
+
import { useEffect, useState } from 'react';
|
|
237
|
+
import { createConsentManager, buildGA4Script } from '@power-seo/tracking';
|
|
274
238
|
|
|
275
|
-
|
|
239
|
+
const consent = createConsentManager({ necessary: true, analytics: false });
|
|
240
|
+
const scripts = buildGA4Script({ measurementId: 'G-XXXXXXX' });
|
|
276
241
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
- ✅ Render consent-gated script tags and GDPR banner via React components
|
|
280
|
-
- ✅ Query analytics data programmatically via 5 provider API clients
|
|
242
|
+
export function AnalyticsLoader() {
|
|
243
|
+
const [state, setState] = useState(consent.getState());
|
|
281
244
|
|
|
282
|
-
|
|
245
|
+
useEffect(() => {
|
|
246
|
+
return consent.onChange(setState);
|
|
247
|
+
}, []);
|
|
283
248
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
249
|
+
const toLoad = scripts.filter((s) => s.shouldLoad(state));
|
|
250
|
+
// inject toLoad scripts into document.head
|
|
251
|
+
return null;
|
|
252
|
+
}
|
|
253
|
+
```
|
|
287
254
|
|
|
288
255
|
---
|
|
289
256
|
|
|
@@ -299,7 +266,7 @@ All 17 packages are independently installable — use only what you need.
|
|
|
299
266
|
| `buildPlausibleScript` | `{ domain, customDomain? }` | `ScriptConfig` | Plausible Analytics |
|
|
300
267
|
| `buildFathomScript` | `{ siteId }` | `ScriptConfig` | Fathom Analytics |
|
|
301
268
|
|
|
302
|
-
|
|
269
|
+
### `ScriptConfig`
|
|
303
270
|
|
|
304
271
|
| Prop | Type | Description |
|
|
305
272
|
| -------------- | ----------------------------------------------------------- | -------------------------------------- |
|
|
@@ -308,11 +275,7 @@ All 17 packages are independently installable — use only what you need.
|
|
|
308
275
|
| `strategy` | `'beforeInteractive' \| 'afterInteractive' \| 'lazyOnload'` | Loading strategy hint |
|
|
309
276
|
| `shouldLoad` | `(consent: ConsentState) => boolean` | Returns `true` if this script may load |
|
|
310
277
|
|
|
311
|
-
###
|
|
312
|
-
|
|
313
|
-
```ts
|
|
314
|
-
function createConsentManager(initialState: Partial<ConsentState>): ConsentManager;
|
|
315
|
-
```
|
|
278
|
+
### `createConsentManager(initialState)`
|
|
316
279
|
|
|
317
280
|
| Method | Signature | Description |
|
|
318
281
|
| ----------- | ------------------------------------------- | ----------------------------------------- |
|
|
@@ -325,13 +288,13 @@ function createConsentManager(initialState: Partial<ConsentState>): ConsentManag
|
|
|
325
288
|
|
|
326
289
|
### API Clients
|
|
327
290
|
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
291
|
+
| Function | Config Props | Returns |
|
|
292
|
+
| ----------------------- | ------------------------------ | ----------------- |
|
|
293
|
+
| `createGA4Client` | `{ measurementId, apiSecret }` | `GA4Client` |
|
|
294
|
+
| `createClarityClient` | `{ projectId, apiKey }` | `ClarityClient` |
|
|
295
|
+
| `createPostHogClient` | `{ apiKey, apiHost? }` | `PostHogClient` |
|
|
296
|
+
| `createPlausibleClient` | `{ domain, apiKey }` | `PlausibleClient` |
|
|
297
|
+
| `createFathomClient` | `{ apiKey }` | `FathomClient` |
|
|
335
298
|
|
|
336
299
|
### React Components
|
|
337
300
|
|
|
@@ -342,64 +305,102 @@ function createFathomClient(config: FathomConfig): FathomClient;
|
|
|
342
305
|
|
|
343
306
|
### Types
|
|
344
307
|
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
```
|
|
308
|
+
| Type | Description |
|
|
309
|
+
| ----------------------- | -------------------------------------------------------------------------------------- |
|
|
310
|
+
| `ConsentCategory` | `'necessary' \| 'analytics' \| 'marketing' \| 'preferences'` |
|
|
311
|
+
| `ConsentState` | `{ necessary: boolean, analytics: boolean, marketing: boolean, preferences: boolean }` |
|
|
312
|
+
| `ConsentManager` | Store with grant/revoke/grantAll/revokeAll/getState/onChange |
|
|
313
|
+
| `ConsentChangeCallback` | `(state: ConsentState) => void` |
|
|
314
|
+
| `ScriptConfig` | `{ src?, inlineScript?, strategy, shouldLoad }` |
|
|
315
|
+
| `GA4Config` | `{ measurementId: string }` |
|
|
316
|
+
| `GA4Client` | GA4 Data API client instance |
|
|
317
|
+
| `ClarityConfig` | `{ projectId: string }` |
|
|
318
|
+
| `ClarityClient` | Clarity API client instance |
|
|
319
|
+
| `PostHogConfig` | `{ apiKey: string, apiHost?: string }` |
|
|
320
|
+
| `PostHogClient` | PostHog API client instance |
|
|
321
|
+
| `PlausibleConfig` | `{ domain: string, customDomain?: string }` |
|
|
322
|
+
| `PlausibleClient` | Plausible Stats API client instance |
|
|
323
|
+
| `FathomConfig` | `{ siteId: string }` |
|
|
324
|
+
| `FathomClient` | Fathom API client instance |
|
|
363
325
|
|
|
364
326
|
---
|
|
365
327
|
|
|
366
|
-
##
|
|
328
|
+
## Use Cases
|
|
329
|
+
|
|
330
|
+
- **GDPR-compliant web apps** — load analytics scripts only after the user grants consent
|
|
331
|
+
- **SaaS marketing sites** — track user behavior with GA4 while respecting privacy regulations
|
|
332
|
+
- **E-commerce stores** — Clarity session recordings for UX optimization with a consent gate
|
|
333
|
+
- **Multi-provider analytics** — run GA4 + Plausible + PostHog side-by-side for data validation
|
|
334
|
+
- **Privacy-first apps** — Plausible or Fathom as cookieless, GDPR-compliant alternatives to GA4
|
|
335
|
+
- **Analytics dashboards** — query GA4, Plausible, or Fathom APIs server-side for custom reporting
|
|
336
|
+
- **A/B testing pipelines** — PostHog feature flags and event tracking with consent management
|
|
337
|
+
- **Enterprise compliance** — full audit trail of when consent was granted per category
|
|
367
338
|
|
|
368
|
-
|
|
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`
|
|
339
|
+
---
|
|
374
340
|
|
|
375
|
-
|
|
341
|
+
## Architecture Overview
|
|
376
342
|
|
|
377
|
-
-
|
|
378
|
-
- `
|
|
343
|
+
- **Pure TypeScript** — no compiled binary, no native modules
|
|
344
|
+
- **Consent-first design** — `shouldLoad(consentState)` is evaluated before any script tag is created
|
|
345
|
+
- **GDPR defaults** — `necessary: true` always; `analytics`, `marketing`, `preferences` default to `false`
|
|
346
|
+
- **SSR-safe builders** — script configs are generated server-side; consent is evaluated client-side
|
|
347
|
+
- **Edge-compatible** — script builders and consent manager have no Node.js-specific APIs; runs in Cloudflare Workers, Vercel Edge, Deno
|
|
348
|
+
- **Optional React peer** — `<AnalyticsScript>` and `<ConsentBanner>` require React 18+; all other exports are framework-agnostic
|
|
349
|
+
- **Dual ESM + CJS** — ships both formats via tsup for any bundler or `require()` usage
|
|
350
|
+
- **Zero runtime dependencies** — pure TypeScript; optional React peer dependency only
|
|
379
351
|
|
|
380
352
|
---
|
|
381
353
|
|
|
382
|
-
##
|
|
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.
|
|
354
|
+
## Supply Chain Security
|
|
385
355
|
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
356
|
+
- No install scripts (`postinstall`, `preinstall`)
|
|
357
|
+
- No runtime network access outside of analytics API calls
|
|
358
|
+
- No `eval` or dynamic code execution
|
|
359
|
+
- npm provenance enabled — every release is signed via Sigstore through GitHub Actions
|
|
360
|
+
- CI-signed builds — all releases published via verified `github.com/CyberCraftBD/power-seo` workflow
|
|
361
|
+
- Safe for SSR, Edge, and browser environments
|
|
392
362
|
|
|
393
363
|
---
|
|
394
364
|
|
|
395
|
-
##
|
|
365
|
+
## The [@power-seo](https://www.npmjs.com/org/power-seo) Ecosystem
|
|
396
366
|
|
|
397
|
-
|
|
367
|
+
All 17 packages are independently installable — use only what you need.
|
|
368
|
+
|
|
369
|
+
| Package | Install | Description |
|
|
370
|
+
| ------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------- |
|
|
371
|
+
| [`@power-seo/core`](https://www.npmjs.com/package/@power-seo/core) | `npm i @power-seo/core` | Framework-agnostic utilities, types, validators, and constants |
|
|
372
|
+
| [`@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 |
|
|
373
|
+
| [`@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 |
|
|
374
|
+
| [`@power-seo/schema`](https://www.npmjs.com/package/@power-seo/schema) | `npm i @power-seo/schema` | Type-safe JSON-LD structured data — 23 builders + 21 React components |
|
|
375
|
+
| [`@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 |
|
|
376
|
+
| [`@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 |
|
|
377
|
+
| [`@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 |
|
|
378
|
+
| [`@power-seo/sitemap`](https://www.npmjs.com/package/@power-seo/sitemap) | `npm i @power-seo/sitemap` | XML sitemap generation, streaming, index splitting, and validation |
|
|
379
|
+
| [`@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 |
|
|
380
|
+
| [`@power-seo/links`](https://www.npmjs.com/package/@power-seo/links) | `npm i @power-seo/links` | Link graph analysis — orphan detection, suggestions, equity scoring |
|
|
381
|
+
| [`@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 |
|
|
382
|
+
| [`@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 |
|
|
383
|
+
| [`@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 |
|
|
384
|
+
| [`@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 |
|
|
385
|
+
| [`@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 |
|
|
386
|
+
| [`@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 |
|
|
387
|
+
| [`@power-seo/tracking`](https://www.npmjs.com/package/@power-seo/tracking) | `npm i @power-seo/tracking` | GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management |
|
|
398
388
|
|
|
399
389
|
---
|
|
400
390
|
|
|
401
391
|
## Keywords
|
|
402
392
|
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
393
|
+
analytics · ga4 · google-analytics · microsoft-clarity · posthog · plausible · fathom · gdpr · consent-management · cookie-consent · typescript · react · nextjs · privacy · script-loader · analytics-api · tracking · seo-analytics · consent-banner · gdpr-compliance
|
|
394
|
+
|
|
395
|
+
---
|
|
396
|
+
|
|
397
|
+
## About [CyberCraft Bangladesh](https://ccbd.dev)
|
|
398
|
+
|
|
399
|
+
**[CyberCraft Bangladesh](https://ccbd.dev)** is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider 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.
|
|
400
|
+
|
|
401
|
+
[](https://ccbd.dev)
|
|
402
|
+
[](https://github.com/cybercraftbd)
|
|
403
|
+
[](https://www.npmjs.com/org/power-seo)
|
|
404
|
+
[](mailto:info@ccbd.dev)
|
|
405
|
+
|
|
406
|
+
© 2026 [CyberCraft Bangladesh](https://ccbd.dev) · Released under the [MIT License](../../LICENSE)
|