Skip to Content

Fullstack

Browser clients, React authentication UI, server handlers, and framework adapters for Puzzle Auth.

@puzzle-ui/fullstack connects Puzzle authentication services to browser applications and server routes. It provides a browser-safe auth client and React components, server-side Request/Response handlers, and adapters for Next.js and TanStack Start. It complements the framework-independent @puzzle-ui/auth and @puzzle-ui/session packages rather than replacing them.

The Fullstack package APIs, including the React auth components on Client and React, are Stable with within-major backward-compatibility intent. This describes API maturity only; it is not a production-readiness guarantee.

Install

Follow the Auth dashboard tutorial for a complete server/client setup, required MFA enrollment, protected routes and logout.

npm install @puzzle-ui/fullstack react react-dom

React and React DOM 19 are required peer dependencies. The next and @tanstack/react-start peers are optional; install the framework you use to enable its adapter. For server setup, your app will also use @puzzle-ui/auth, @puzzle-ui/session, and a configured storage backend. See Auth, Storage, and the authentication implementation guide for the service and persistence layers.

Quick start

Wrap the client application in AuthProvider. It creates a client using /api/auth by default and loads the authentication snapshot from the server.

import { AuthProvider } from "@puzzle-ui/fullstack/auth/client";

export const Providers = ({ children }: { children: React.ReactNode }) => (
  <AuthProvider>{children}</AuthProvider>
);

Create and configure an AuthServer from your server-side auth and session managers, then connect it to framework routes. The adapters and exact setup are covered in the pages below.

What the package provides

AreaDescriptionDocumentation
Client and React UIBrowser client, provider and hooks, authentication forms, MFA settings, and configurable sign-in/sign-up experience.Client and React
Server handlersAuthentication, MFA, sessions, lifecycle, route map, readiness checks, and step-up helpers.Server handlers
Next.js adapterGET and POST handlers for a Next.js route handler.Next.js
TanStack Start adapterA Request dispatcher or explicit route map for TanStack Start.TanStack Start
Shared contractsSerializable client snapshots, inputs, and result types shared across runtimes.Shared types

Package entry points

ImportUse
@puzzle-ui/fullstack/auth/clientBrowser client, React provider, hooks, UI, localization helpers, and passkey browser helpers.
@puzzle-ui/fullstack/auth/serverServer construction, route map, request/session helpers, MFA and lifecycle handlers, and readiness checks.
@puzzle-ui/fullstack/auth/sharedShared TypeScript data contracts only; no runtime values.
@puzzle-ui/fullstack/auth/nextNext.js route-handler adapter.
@puzzle-ui/fullstack/auth/tanstackTanStack Start request-handler adapter.

There is no package-root import; use one of the exported subpaths above. Keep auth policy and storage configuration in the appropriate lower-level packages, and use Fullstack to connect them to your app. For the end-to-end app setup, continue with the developer authentication guide.