frontend-observability

What it does

Implements a portable observability system for React and React Native apps. It defines a single typed set of event constants, exposes a single entry point track(event, props), and fans out to multiple analytics adapters in a non-blocking, SSR-safe manner. It enforces a consent gate so no telemetry runs before opt-in, and provides a hook-based client-side API via a provider to access track without affecting server components.

How it works

• Central event taxonomy: events live in a constants/analytics.ts file as ANALYTICS_EVENTS with an AnalyticsEvent union type; events are referenced via ANALYTICS_EVENTS.* and never as string literals.
• Single entry point: track(event, props) is the unified function; it checks consent (hasConsent()) and then iterates analyticsAdapters, calling each adapter inside a try/catch to prevent a failing provider from breaking others.
• Adapters: each provider has a tiny function (event, props) => void guarded by SSR-safe checks (e.g., window presence, provider readiness). The registry analyticsAdapters is exported and mutable for testability.
• Platform support: separate firebase adapters for web and native, loaded via lazy/guarded imports or platform-specific files; the track fan-out remains stable across platforms.
• SSR-safe provider: AnalyticsProvider exposes a useAnalytics() hook; outside a provider or on server, useAnalytics returns a no-op track function. A TrackedGithubLink component demonstrates using the hook client-side.
• Real-user vitals: web-vitals integration reports to track with event name 'web_vital' and properties like name, value, rating, id, reusing the same fan-out.
• Consent and privacy: hasConsent gates all dispatch; track returns early if consent is absent.

When to use it

Use this skill when you need a portable, framework-agnostic field-side observability system for any React or React Native app. It establishes a typed event taxonomy, best-effort non-blocking fan-out, field vitals, and consent gating, serving as a field complement to the frontend-lighthouse lab skill.

What it can touch

• Adapters: googleAnalyticsAdapter, clarityAdapter, firebaseAdapter, firebase.native adapter, plus others (registry shows multiple entries).
• Event taxonomy: ANALYTICS_EVENTS constants and AnalyticsEvent union.
• Web vitals reporting via reportWebVitals which calls track with a web_vital event.
• Consent and privacy: hasConsent() gating in track and consent.ts.

Caveats

• The risk is marked as critical. The implementation relies on browser globals and optional providers; SSR-safe guards are required to prevent crashes.
• No inline strings for event names; must use ANALYTICS_EVENTS.* constants.
• The system depends on external provider scripts (e.g., GA, Clarity, PostHog) being loaded at runtime; adapters guard for absence and errors to avoid breaking the app.