@playstack/analytics-react

@playstack/analytics-react supplies an existing analytics instance through React context, makes consent reactive, and offers explicit Pages and App Router navigation adapters.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/analytics-react@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Compose the provider

import { PlaystackAnalyticsProvider, useAnalytics, useAnalyticsConsent } from '@playstack/analytics-react'

function ApplicationProviders({ children }) {
  return (
    <PlaystackAnalyticsProvider analytics={analytics}>
      {children}
    </PlaystackAnalyticsProvider>
  )
}

function UpgradeButton() {
  const analytics = useAnalytics()
  return <button onClick={() => analytics.track('upgrade_selected')}>Upgrade</button>
}

The provider accepts only analytics and children. useAnalytics() returns that exact core instance, including native clients. useAnalyticsConsent() returns reactive { state, setConsent } controls.

Consent ownership

Restore durable consent on the core instance before rendering, then persist changes made through the hook in application settings or compliance storage. This package owns only React reactivity; it does not store evidence.

Next.js Pages Router bridge

import { usePagesRouterAnalytics } from '@playstack/analytics-react/next-pages'

usePagesRouterAnalytics(useRouter(), {
  enabled: true,
  trackShallow: false,
  shouldTrack: ({ url }) => !url.startsWith('/account/private'),
  resolvePage: ({ url }) => ({
    title: document.title,
    properties: { section: url.split('/')[1] || 'home' },
  }),
  onError: (error) => errors.captureError(error),
})

The structural router bridge records the initial ready URL and completed navigation only, skips duplicate URLs, and has no next dependency.

Next.js App Router bridge

'use client'

import { Suspense } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'

import { useAppRouterAnalytics } from '@playstack/analytics-react/next-app'

function AnalyticsRoutes() {
  useAppRouterAnalytics(usePathname(), useSearchParams(), {
    shouldTrack: ({ pathname }) => !pathname.startsWith('/account/private'),
  })
  return null
}

export function AnalyticsNavigation() {
  return (
    <Suspense fallback={null}>
      <AnalyticsRoutes />
    </Suspense>
  )
}

The App Router effect observes committed pathname and query values, records the first available URL, and skips duplicates. The application owns the Suspense boundary required by useSearchParams() in statically rendered routes.

Boundary

The package does not initialize SDKs, persist consent, emit domain events, publish artifacts, or impose a router. Those choices remain application inputs.

API entry points and requirements

Reference snapshot: @playstack/analytics-react@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.