Quick reference

CLI commands

Bash

# Add UI components (Login, Register, Forgot Password, etc.)
npx @fivfold/ui add auth

# Add backend scaffolding (Express/NestJS + Firebase/Cognito/Auth0/JWT)
npx @fivfold/api add auth --framework=nestjs --provider=firebase

# Dry run to preview files
npx @fivfold/ui add auth --dry-run
npx @fivfold/api add auth --dry-run

Overview

The Auth Kit provides ready-to-use authentication screens that call useAuth().login(), register(), forgotPassword(), and more. Provider-specific wiring lives in auth-provider.tsx. Choose Firebase, AWS Cognito, Auth0, or JWT when scaffolding.

Provider Flexibility

All screens use the same useAuth() hook. Swap the AuthProvider implementation to switch between Firebase, Cognito, Auth0, or custom JWT—no changes to the UI components.

Demo

This demo is presented with Mock Data

Welcome back

Or sign in with

Don't have an account?

By clicking continue, you agree to our Terms of Service and Privacy Policy.

Guide

Step-by-step guides for the frontend UI and backend API integration. Select Frontend first in the sidebar, then Auth provider and the rest of your stack.

The Auth Kit is built on shadcn/ui. The steps below follow the standard kit doc order (see AGENTS.md). Stack sidebar: Firebase drives install command and integration notes.

1Install the Auth Kit

Run the FivFold UI CLI to add the Auth Kit. Pass --provider firebase to match your backend.

Bash

npx @fivfold/ui add auth --provider firebase

The Kit is copied to @/components/ui/kits/auth/ (or your configured kits alias in fivfold.json).

2Generated file structure

The command creates a folder with screen components and Firebase-specific wiring:

File tree

kits/auth/
  types.ts             # AuthContextValue, LoginFormProps, etc.
  auth-layout.tsx      # Shared layout: split-pane (form + branding)
  auth-provider.tsx    # AuthProvider context + useAuth() (wired to Firebase)
  login.tsx            # LoginForm
  register.tsx         # RegisterForm
  forgot-password.tsx  # ForgotPasswordForm
  reset-password.tsx   # ResetPasswordForm
  email-verification.tsx # EmailVerification
  oauth-buttons.tsx    # OAuthButtons (Google, GitHub, Apple icons)
  auth-guard.tsx       # AuthGuard for protected routes
  providers/           # Provider-specific client SDK wiring
    firebase-client.ts
  index.tsx            # Re-exports

3Import and use in your app

Wrap your app with AuthProvider and use the screens in your routes:

app/auth/layout.tsx

import { AuthProvider, LoginForm, RegisterForm } from "@/components/ui/kits/auth";

export function AuthLayout() {
  return (
    <AuthProvider>
      <Routes>
        <Route path="/login" element={
          <LoginForm
            onForgotPassword={() => navigate("/forgot")}
            oauthProviders={["google", "github", "apple"]}
            logoSrc="/logo.png"
            appName="Acme Inc"
            footerContent={<SignUpLink />}
          />
        } />
        <Route path="/register" element={<RegisterForm oauthProviders={["google", "github", "apple"]} logoSrc="/logo.png" appName="Acme Inc" />} />
      </Routes>
    </AuthProvider>
  );
}

4Props reference

The Auth Kit exposes form components and AuthProvider. Props vary by screen.

LoginForm

Email/password + OAuth buttons with branded logos. Uses AuthLayout, Input, Label, Button, Separator.

Prop	Type	Purpose
onSubmit	(email, password) => Promise	Called with credentials. Wire to useAuth().login().
onForgotPassword	() => void	Navigate to forgot-password screen.
oauthProviders	("google" \| "github" \| "apple")[]	OAuth buttons to show. Varies per AuthProvider.
logoSrc	string	Logo image URL for branding area.
appName	string	App name for subheading (e.g. "Login to your Acme Inc account").
termsHref	string	Terms of Service URL for footer.
privacyHref	string	Privacy Policy URL for footer.
footerContent	ReactNode	Footer (e.g. "Don't have an account? Sign up" link).

RegisterForm

Registration with display name. Uses AuthLayout, Input, Label, Button, Separator. Inherits logoSrc, appName, termsHref, privacyHref from AuthLayoutFormProps.

Prop	Type	Purpose
onSubmit	(email, password, displayName?) => Promise	Wire to useAuth().register().
oauthProviders	("google" \| "github" \| "apple")[]	OAuth buttons to show.

ForgotPasswordForm, ResetPasswordForm, EmailVerification

ForgotPasswordForm: request reset link. ResetPasswordForm: new password (token from URL). EmailVerification: status + resend.

Component	Key props
ForgotPasswordForm	onSubmit(email), onBackToLogin
ResetPasswordForm	token, onSubmit(token, newPassword), onBackToLogin
EmailVerification	onResend, onBackToLogin

AuthLayout

Shared wrapper: responsive split-pane (form left, branding right on desktop), logo slot, Terms & Privacy footer. All form components use it internally.

Prop	Type	Purpose
logoSrc	string	Logo image URL. Shown in branding pane (desktop) or above form (mobile).
appName	string	App name for subheading.
heading	string	Main heading (e.g. "Welcome back").
subheading	string	Secondary text below heading.
termsHref	string	Terms of Service URL for footer link.
privacyHref	string	Privacy Policy URL for footer link.
footer	ReactNode	Optional footer content (e.g. sign up link).

AuthProvider & AuthGuard

AuthProvider wraps the app and exposes useAuth(). AuthGuard protects routes.

Prop	Type	Purpose
AuthProvider children	ReactNode	App tree. useAuth() available in descendants.
AuthGuard children	ReactNode	Protected content. Redirects if unauthenticated.
AuthGuard redirectTo	string	Redirect path when unauthenticated.

5Integration with backend

You own the wiring

The step-by-step guides, environment variables, and dev-server proxy or rewrite examples are suggestions—not a mandated layout. You should read the generated files, your existing routes and auth, and your deployment topology, then choose URLs, origins, and headers that match your app. We encourage verifying every connection yourself before shipping.

Step-by-step: Auth UI → API

Examples match the Frontend choice in the stack sidebar (Next.js). Your mount paths may differ; adjust prefixes to match how you register routes and proxies.

Next.js → API

Prefer rewrites in next.config.ts so browser code can use same-origin paths like /api/auth/... while the dev server forwards to your backend. Alternatively set NEXT_PUBLIC_API_URL and call that base from client code.

next.config.ts

// next.config.ts — example rewrite to API on another port
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'http://localhost:3001/:path*', // your Nest/Express port
      },
    ];
  },
};

export default nextConfig;

If the app and API both use port 3000, run the API on a different port (e.g. 3001) or use a monorepo BFF pattern.

API → browser (CORS)

Allow your UI's dev origin on the API. For Next.js that is typically http://localhost:3000 (plus 127.0.0.1 if you use it).

Production

Use your real API base (e.g. https://api.example.com/auth) and lock CORS to known web origins — not *.

Realtime: Session refresh and OAuth callbacks often need absolute URLs aligned with your deployed web origin and API base.

Connecting Auth (UI layer) data to your user system

Screens call your chosen provider SDK or your JWT API. The user id the rest of your app uses must match what the backend puts in tokens or session.

After login, persist or expose the same user identifier your Email, Kanban, Chat, or Push APIs expect in guards.
For JWT mode, point the Auth Kit’s client helpers at the real base URL of your auth module.
OAuth redirect URIs and authorized domains must include every environment where you test (localhost, preview, prod).

Inspect generated code

Open the scaffolded entities, schemas, or Prisma models for this kit and compare field names (userId, ownerId, etc.) to your User table or IdP subject. Migrate or add FKs where needed—FivFold cannot know your prior schema.

Firebase client, env, and proxy

Firebase Authentication provides email/password, OAuth (Google, GitHub, Apple), and email verification out of the box. The Auth Kit wires Firebase Auth SDK to the shared UI components.

Create a Firebase project

Go to Firebase Console, create a project, and enable Authentication. Enable Email/Password and the OAuth providers (Google, GitHub, Apple) you need.

Add Firebase config

Copy your Firebase config from Project Settings → General → Your apps. Add the variables to .env.local.

Configure OAuth redirect domains

In Firebase Console → Authentication → Settings → Authorized domains, add your app domain (e.g. localhost for dev). For Google/GitHub/Apple, add the redirect URLs in each provider's console.

Environment variables required in .env.local:

.env.local

NEXT_PUBLIC_FIREBASE_API_KEY
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN
NEXT_PUBLIC_FIREBASE_PROJECT_ID
NEXT_PUBLIC_FIREBASE_APP_ID

Example provider wiring in providers/firebase-client.ts:

providers/firebase-client.ts

// providers/firebase-client.ts
import { initializeApp } from "firebase/app"
import { getAuth, connectAuthEmulator } from "firebase/auth"

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
}

const app = initializeApp(firebaseConfig)
export const auth = getAuth(app)

export async function signInWithGoogle() {
  const { signInWithPopup, GoogleAuthProvider } = await import("firebase/auth")
  return signInWithPopup(auth, new GoogleAuthProvider())
}

OAuth

Firebase Auth handles OAuth popups internally. Ensure signInWithPopup is allowed in your browser (no third-party cookies blocked).

6Third-party integrations

Firebase Authentication — client SDK used by the generated providers/firebase-client.ts.

7Shadcn primitives dependencies

Adding the Auth Kit installs these shadcn/ui primitives if not already present:

Component	Used in
button	Submit, OAuth (with logos), actions
input	Email, password fields
label	Form labels
separator	OAuth divider

8Additional dependencies

Non-shadcn packages used by the kit:

@icons-pack/react-simple-icons — Apple, Google, GitHub logos in oauth-buttons.tsx.
next/image — logo in AuthLayout when you use Next.js (Vite projects swap for a regular <img>).