Next.js

Install the edges you use

Next.js can host browser UI, server rendering, route handlers, and application composition. Playstack adapters describe the router and runtime boundary they actually support instead of claiming every Next.js surface implicitly.

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

Connect the browser to application routes

import { PlaystackAuthProvider, createFetchAuthTransport } from '@playstack/auth-react'

const transport = createFetchAuthTransport({
  sessionEndpoint: '/api/auth/session',
  refreshEndpoint: '/api/auth/refresh',
  signInEndpoint: '/api/auth/sign-in',
  signOutEndpoint: '/api/auth/sign-out',
  headers: () => ({ 'x-csrf-token': readCsrfCookie() }),
})

export function ApplicationProviders({ children, session }) {
  return (
    <PlaystackAuthProvider transport={transport} initialSession={session}>
      {children}
    </PlaystackAuthProvider>
  )
}

Those four routes belong to the application. They translate HTTP and cookies into calls to the configured portable auth service, validate CSRF where cookies are ambient, and return only AuthSessionView. When the API is a separate origin, use createBearerAuthTransport with the API's baseUrl and drop the CSRF header: the API answers { session, accessToken, accessExpiresAt } and protects its cookie routes with Origin and Sec-Fetch-Site checks for browser requests (PlaystackOriginGuard in @playstack/nest-auth), while non-browser clients reach the same routes with a bearer token.

Compose SSR session handoff

import { createAuthNextHelpers } from '@playstack/auth-next/pages'

export const { requireSession, withSession } = createAuthNextHelpers({
  resolveSession: ({ req }) => resolveSafeSessionView(req),
})

Hydrate the same validated session into PlaystackAuthProvider for client navigation without an unauthenticated flash.

Choose the router boundary explicitly

For a Pages Router page, use withSession when authentication is optional and requireSession when the page must redirect before rendering.

For an App Router application, create helpers from @playstack/auth-next/app. The resolver still belongs in a server-only application module, while Next's redirect() or a route-handler response is supplied as the explicit unauthenticated boundary. This supports Server Components and route handlers without hiding cookie access, cache policy, middleware, or server-action authorization.

import { redirect } from 'next/navigation'

import { createAppRouterAuthHelpers } from '@playstack/auth-next/app'

const auth = createAppRouterAuthHelpers({
  resolveSession: () => resolveSessionViewFromCookies(),
})

export default async function AccountPage() {
  const session = await auth.requireSession({
    redirectTo: '/login',
    onUnauthenticated: (destination) => redirect(destination ?? '/login'),
  })

  return <Account userId={session.user.id} />
}

Provider sign-in follows the same rule. Auth.js may own its provider handshake while @playstack/auth-authjs normalizes the callback into Playstack identity policy. Email/password and magic-link routes can call the portable credential service directly. See the Authentication feature guide to choose the entry path.

Add capabilities independently

Account switching adds @playstack/accounts-react; feeds and sitemaps add @playstack/feeds-next. Shared ISR adds @playstack/cache-next, while search routes can use @playstack/search-next independently of either. None requires rebuilding the authentication boundary. Follow each supported feature above to see its frontend, server, persistence, and provider dependencies.

Router boundaries

Auth, content, search, and cache adapters publish explicit router boundaries where their contracts differ. Analytics publishes ./next-pages and ./next-app, while feeds produces App Router-compatible route handlers. Provider SDKs, cookies, redirects, cache policy, environment loading, and database clients remain in the application composition root.

Application UI compositions

The optional UI stack now includes Chakra themes, app shells/navigation, settings, tables, commands, Kanban and resizable panes, plus the first account-admin shell and members section. These are React DOM compositions, separate from the headless domain bindings.

Prebuilt and custom Next routes use an application-owned shell and server authorization. Create Chakra systems in client-owned modules; keep interactive callbacks behind Client Component boundaries. Global staff and impersonation flows are still to come; verify browser behavior in your own product. See UI packages.

Localized UI without another router

Use i18n-react for shared App UI/Admin UI catalogs, or compose its message provider alongside the application's existing locale library. Keep SSR/client locale, time zone and direction consistent. Playstack does not install a locale router or ICU runtime. See UI localization.