Getting started with React

Start with one client capability and one operational boundary. This guide supplies session state to the component tree and reports render failures without coupling the application to a particular auth server, router, or monitoring vendor.

1. Install the core and binding pairs

Before you start: use an existing React app and a working authentication API. This guide wires that API to React; it does not create a backend. For a complete first program without a server, try the storage quickstart. Confirm package access before installing.

The composition example assumes errors is a configured Errors service, ErrorScreen is your recovery UI, and initialSession is the safe session value from your server. readCsrfCookie is your cookie-reading helper for the same-origin option, not a Playstack export. Choose one transport using the Auth React guide; the example API hostname is a placeholder for your own service.

npm install @playstack/auth @playstack/auth-react @playstack/errors @playstack/errors-react react

Keep all @playstack/* dependencies on the same fixed version. The React packages are bindings, so their portable core peers remain explicit application dependencies.

2. Configure application-owned edges

Create the error reporter with the drivers your application already uses. Create the auth transport that matches where the API lives. When the API is served from the same origin as the page, the cookie transport carries the session cookie and echoes the CSRF cookie your routes issue; when the API is a different origin, the bearer transport keeps a short-lived access token in memory and needs no CSRF header, because the API checks Origin and Sec-Fetch-Site instead:

import {
  PlaystackAuthProvider,
  createBearerAuthTransport,
  createFetchAuthTransport,
} from '@playstack/auth-react'
import { ErrorsBoundary, ErrorsProvider } from '@playstack/errors-react'

// Same origin: cookies plus the synchronizer header your routes require.
const sameOriginTransport = createFetchAuthTransport({
  headers: () => ({ 'x-csrf-token': readCsrfCookie() }),
})

// Split origin: HTTPS (or loopback in development), no CSRF header.
const transport = createBearerAuthTransport({
  baseUrl: 'https://api.example.com',
})

export function ApplicationRoot({ children, initialSession }) {
  return (
    <ErrorsProvider errors={errors}>
      <ErrorsBoundary
        fallback={({ error, reset }) => (
          <ErrorScreen error={error} onRetry={reset} />
        )}
      >
        <PlaystackAuthProvider
          transport={transport}
          initialSession={initialSession}
        >
          {children}
        </PlaystackAuthProvider>
      </ErrorsBoundary>
    </ErrorsProvider>
  )
}

Either transport includes cookies but never reads an HTTP-only cookie. The application supplies the synchronizer header only for the same-origin cookie transport and may replace the endpoint paths or fetch implementation on both. After an account switch with the bearer transport, call refresh from useAuth() so the transport adopts the rotated refresh cookie.

3. Read state without hiding loading

import { RequireSession, useAuth, useSession } from '@playstack/auth-react'

function AccountArea() {
  const { status, user, error } = useSession()
  const { signOut } = useAuth()

  if (status === 'loading') return <LoadingAccount />
  if (error) return <SessionProblem error={error} />

  return (
    <RequireSession fallback={<SignInPrompt />}>
      <p>Signed in as {user?.name}</p>
      <button onClick={() => signOut()}>Sign out</button>
    </RequireSession>
  )
}

Treat RequireSession as navigation UX. The API serving the protected data must independently verify the session and authorization context.

4. Add providers as capabilities appear

• Add @playstack/accounts-react when users can switch account context. The server still validates membership on each scoped request.
• Add @playstack/analytics-react after the core analytics instance has restored durable consent.
• Use useErrors() for event-handler and effect failures so they pass through the same scrubbed reporter as render errors.

Keep provider configuration in one application composition module. Components should consume the narrow hooks, while infrastructure clients and secrets stay outside the React tree.

Optional application UI

Chakra, App UI and Admin UI add themes, controlled application compositions and the initial scoped members section. These are independent of auth/backend adoption. The host owns routes, data, mutations and authorization; Next Client Components hold callbacks and the Chakra system. See Application interfaces.