@ackplus/nest-auth-react

React provider, hooks, guards, and first-class Next.js App Router helpers for @ackplus/nest-auth. Headless — bring your own UI.

📚 Full documentation: ack-solutions.github.io/nest-auth/docs/react

Why use it

A thin React layer on top of @ackplus/nest-auth-client that gives you everything you'd build by hand: a context provider, narrow re-rendering hooks, guard components, route-level guards via Next.js Server Components, and cross-tab sync.

It's headless — no styled buttons, no opinionated forms — so it drops into any React 18 / 19 app or Next.js App Router project without fighting your design system.

Install

pnpm add @ackplus/nest-auth-react @ackplus/nest-auth-client

AI coding agents

Using Claude Code, Codex, Cursor or another AI coding agent? Install the Nest Auth skill so it knows this SDK's real API:

npx @ackplus/nest-auth-skill

It detects your stack (or pass --stack react) and only adds agent instruction files; your app is not changed.

What's included

Minimal example — SPA

import { AuthClient } from '@ackplus/nest-auth-client';
import { AuthProvider, useNestAuth, AuthGuard, useUser } from '@ackplus/nest-auth-react';

const client = new AuthClient({ baseUrl: 'https://api.example.com' });

export default function App() {
  return (
    <AuthProvider client={client}>
      <Routes />
    </AuthProvider>
  );
}

function Dashboard() {
  return (
    <AuthGuard fallback={<a href="/login">Sign in</a>}>
      <DashboardInner />
    </AuthGuard>
  );
}

function DashboardInner() {
  const user = useUser();
  return <h1>Hello {user?.email}</h1>;
}

function LoginForm() {
  const { login, error, isLoading } = useNestAuth();
  return (
    <form onSubmit={async (e) => {
      e.preventDefault();
      await login({ credentials: { email, password } });
    }}>
      {/* … */}
      <button disabled={isLoading}>Sign in</button>
      {error && <p>{error.message}</p>}
    </form>
  );
}

Minimal example — Next.js App Router

// app/layout.tsx (Server Component)
import { cookies } from 'next/headers';
import { NextAuthProvider } from '@ackplus/nest-auth-react';
import { client, authHelpers } from '@/lib/auth';

export default async function RootLayout({ children }) {
  const initialState = await authHelpers.getServerAuth(await cookies());

  return (
    <html lang="en">
      <body>
        <NextAuthProvider client={client} initialState={initialState}>
          {children}
        </NextAuthProvider>
      </body>
    </html>
  );
}

// app/api/private/route.ts
import { authHelpers } from '@/lib/auth';

export const GET = authHelpers.withAuth(async (req) => {
  return Response.json({ user: req.auth.user });
});

Full Next.js guide →

Role & permission gating

import { RequireRole, RequirePermission, useHasRole } from '@ackplus/nest-auth-react';

<RequireRole role="admin" fallback={<NotAuthorized />}>
  <AdminPanel />
</RequireRole>

<RequirePermission permission={['orders.read', 'orders.write']} matchAll>
  <OrderEditor />
</RequirePermission>

// Or via hook
const isAdmin = useHasRole('admin');

Documentation

Companion packages

All four packages release together with the same version number. Pin them all to the same version.

Links

• 📚 Documentation
• 💬 Issue Tracker
• 📦 GitHub Repository

License

MIT