@playstack/audiences-react

Headless React subscription and preference-center state with explicit clients, cache boundaries, and safe errors.

Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.

@playstack/audiences-react supplies headless state for subscribe forms and token-scoped preference centers. The package root is an explicit Client Component entry point that can sit beneath a Next.js App Router Server Component boundary.

Install

npm install @playstack/audiences-react @playstack/audiences react

'use client'

import {
  createAudiencesCache,
  PlaystackAudiencesProvider,
  useAudienceSubscribe,
} from '@playstack/audiences-react'

const cache = createAudiencesCache()

function Subscribe() {
  const subscription = useAudienceSubscribe({ listKey: 'launch' })

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault()
        void subscription.submit(
          new FormData(event.currentTarget).get('email') as string,
        )
      }}
    >
      <input name="email" type="email" />
      <button disabled={subscription.status === 'loading'}>Subscribe</button>
    </form>
  )
}

export function AudienceBoundary() {
  return (
    <PlaystackAudiencesProvider client={applicationClient} cache={cache}>
      <Subscribe />
    </PlaystackAudiencesProvider>
  )
}

Provider configuration

Property	Required	Purpose
`client`	Yes	Application-owned subscribe and preference API client.
`cache`	Yes	Explicit synchronous `get`/`set`/`subscribe` boundary.
`toSafeError`	No	Maps application errors to approved UI copy.
`onError`	No	Sends the original error to caller-owned observability.

client.client preserves access to the underlying HTTP or query client. The package does not install a fetch global, authentication, CAPTCHA, routing, or visual styling.

Hooks and headless components

API	Purpose
`useAudienceSubscribe({ listKey, cacheKey? })`	Submits an address, shares in-flight operations, and reports accepted or confirmation-required state.
`useAudiencePreferences({ token, cacheKey })`	Loads and optimistically updates token-scoped preferences.
`AudienceSubscribe`	Render-prop equivalent of the subscribe hook.
`AudiencePreferenceCenter`	Render-prop equivalent of the preferences hook.

The preference cacheKey must be a stable, non-secret identifier. The signed token is intentionally never used as a cache key. Public subscribe responses containing subscriber IDs or signed tokens are rejected as invalid.

API entry points and requirements

Reference snapshot: @playstack/audiences-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.

Public entry point	Declaration file
`@playstack/audiences-react`	`./dist/index.d.ts`
`@playstack/audiences-react/errors`	`./dist/errors.d.ts`
`@playstack/audiences-react/package.json`	No TypeScript declaration (asset or metadata export).

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.

Peer	Compatible range	When needed
`@playstack/audiences`	`0.1.0-beta.1`	Required by the package.
`react`	`^18.2.0 \|\| ^19.0.0`	Required by the package.

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.