Quickstart

By the end of this guide you will have AilitaProvider wrapping your app, AuthGuard protecting a route, LoginForm handling authentication, and useAuth displaying the current user.

What you’ll build

providers.tsx — AilitaProvider wrapper with tenant config
(protected)/layout.tsx or ProtectedRoute.tsx — AuthGuard route protection
login/page.tsx or LoginPage.tsx — Login page with LoginForm
dashboard/page.tsx or DashboardPage.tsx — Protected page using useAuth

Install and configure

See Installation for full setup details including Tailwind CSS.

npm install ailita-library

// Root layout or entry file
import 'ailita-library/styles'

Create the Providers wrapper

Always include onSessionExpired. Without it, expired sessions silently break the app — users get stuck with no feedback and no path back to login.

// app/providers.tsx
'use client'

import { AilitaProvider } from 'ailita-library'
import { useRouter } from 'next/navigation'

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter()
  return (
    <AilitaProvider
      clientId="pk_live_your_client_id"
      baseUrl="https://api.yourdomain.com/api/v1"
      onSessionExpired={() => router.push('/login')}
      loadingFallback={<div>Loading...</div>}
      errorFallback={<div>Could not reach the server.</div>}
    >
      {children}
    </AilitaProvider>
  )
}

// src/providers.tsx
import { AilitaProvider } from 'ailita-library'
import { useNavigate } from 'react-router-dom'

export function AppProviders({ children }: { children: React.ReactNode }) {
  const navigate = useNavigate()
  return (
    <AilitaProvider
      clientId="pk_live_your_client_id"
      baseUrl="https://api.yourdomain.com/api/v1"
      onSessionExpired={() => navigate('/login')}
      loadingFallback={<div>Loading...</div>}
      errorFallback={<div>Could not reach the server.</div>}
    >
      {children}
    </AilitaProvider>
  )
}

Wrap your root layout

// app/layout.tsx
import { Providers } from './providers'
import 'ailita-library/styles'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

// src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { BrowserRouter } from 'react-router-dom'
import { AppProviders } from './providers'
import App from './App'
import 'ailita-library/styles'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <BrowserRouter>
      <AppProviders>
        <App />
      </AppProviders>
    </BrowserRouter>
  </StrictMode>
)

Protect a route with AuthGuard

Always include loadingFallback. Omitting it causes a redirect flash for every authenticated user on each page load during the ~200–500ms silent token refresh on mount.

// app/(protected)/layout.tsx
'use client'

import { AuthGuard } from 'ailita-library'
import { useRouter } from 'next/navigation'
import { useEffect } from 'react'

export default function ProtectedLayout({ children }: { children: React.ReactNode }) {
  return (
    <AuthGuard
      fallback={<RedirectToLogin />}
      loadingFallback={<div>Loading...</div>}
    >
      {children}
    </AuthGuard>
  )
}

function RedirectToLogin() {
  const router = useRouter()
  useEffect(() => { router.push('/login') }, [router])
  return null
}

// src/components/ProtectedRoute.tsx
import { AuthGuard } from 'ailita-library'
import { Navigate } from 'react-router-dom'

export function ProtectedRoute({ children }: { children: React.ReactNode }) {
  return (
    <AuthGuard
      fallback={<Navigate to="/login" replace />}
      loadingFallback={<div>Loading...</div>}
    >
      {children}
    </AuthGuard>
  )
}

Add a login page with LoginForm

import { LoginForm } from 'ailita-library'

// Next.js: app/login/page.tsx  |  React Router: src/pages/LoginPage.tsx
export default function LoginPage() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <LoginForm />
    </div>
  )
}

LoginForm handles all login states internally: password submission, OTP challenges, TOTP verification, and TOTP setup on first admin login. No additional wiring required for the basic case.

Read the current user in a protected page

import { useAuth } from 'ailita-library'

export default function DashboardPage() {
  const { user, logout } = useAuth()

  return (
    <div>
      <h1>Welcome, {user?.firstName}</h1>
      <p>{user?.email}</p>
      <button onClick={logout}>Sign out</button>
    </div>
  )
}

user is null on initial render while the silent refresh runs. AuthGuard ensures this page only renders when isAuthenticated is true, so by the time this component mounts, user will be populated.

Getting started

Auth & identity

Session management

Component reference

Security

What you’ll build

Next steps

AilitaProvider props

AuthGuard patterns

​What you’ll build

​Next steps

AilitaProvider props

AuthGuard patterns

What you’ll build

Next steps