Skip to main content
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
1

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'
2

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
      slug="your-merchant-slug"
      appId="your-app-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>
  )
}
3

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>
  )
}
4

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
}
5

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.
6

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.

​
Next steps

AilitaProvider props

Full prop reference for slug, appId, baseUrl, onSessionExpired, and more.

AuthGuard patterns

Role-based access, loadingFallback, and the UX-gate security model.