[INTEGRATION]: NEXTAUTH_V5

NextAuth v5 Integration

Add authentication to library templates with NextAuth v5, session management, and protected routes.

Time: ~15 minutes

Level: Intermediate

[0x00] OVERVIEW

Fabrk uses NextAuth v5 (Auth.js) for authentication. All templates assume authenticated users and need session data for features like user profiles, protected routes, and personalized content.

[WHAT YOU'LL INTEGRATE]:

Session management and JWT tokens (30-day expiry)
Protected route middleware
User object access in templates
Server-side and client-side authentication

[0x01] PREREQUISITES

Fabrk already includes NextAuth v5. Verify your setup:

1$# Check NextAuth is installed
2$npm list next-auth
3
4$# Should show: next-auth@5.0.0-beta.x
5
6$# Verify config files exist
7$ls -la src/lib/auth.ts
8$ls -la src/app/api/auth/[...nextauth]/route.ts

[NOTE] Already Setup?

If you're using Fabrk boilerplate, NextAuth is already configured in src/lib/auth.ts. Skip to Step 2.

[0x02] STEP 1: ENVIRONMENT VARIABLES

Add required environment variables to .env.local:

1$# NextAuth Configuration
2$NEXTAUTH_URL="http://localhost:3000"
3$NEXTAUTH_SECRET="your-32-character-secret-here"
4
5$# OAuth Providers (optional)
6$GOOGLE_CLIENT_ID="your-google-client-id"
7$GOOGLE_CLIENT_SECRET="your-google-client-secret"
8
9$GITHUB_CLIENT_ID="your-github-client-id"
10$GITHUB_CLIENT_SECRET="your-github-client-secret"

[GENERATE SECRET]:

1$# Generate secure random secret
2$openssl rand -base64 32

[0x03] STEP 2: ACCESS SESSION IN TEMPLATES

Server Components (Recommended):

1import { auth } from "@/lib/auth";
2
3export default async function DashboardPage() {
4  const session = await auth();
5
6  if (!session?.user) {
7    redirect("/auth/sign-in");
8  }
9
10  return (
11    <div>
12      <h1>Welcome, {session.user.name}!</h1>
13      <p>Email: {session.user.email}</p>
14    </div>
15  );
16}

Client Components:

1"use client";
2
3import { useSession } from "next-auth/react";
4
5export default function ProfileCard() {
6  const { data: session, status } = useSession();
7
8  if (status === "loading") {
9    return <div>Loading...</div>;
10  }
11
12  if (!session?.user) {
13    return <div>Not authenticated</div>;
14  }
15
16  return (
17    <div>
18      <h2>{session.user.name}</h2>
19      <p>{session.user.email}</p>
20    </div>
21  );
22}

[0x04] STEP 3: PROTECT ROUTES

Use middleware to protect entire route groups:

1// middleware.ts (root level)
2export { auth as middleware } from "@/lib/auth";
3
4export const config = {
5  matcher: [
6    "/dashboard/:path*",  // Protect all dashboard routes
7    "/settings/:path*",   // Protect settings
8    "/api/user/:path*",   // Protect user API routes
9  ],
10};

Or protect individual pages:

1// app/(dashboard)/analytics/page.tsx
2import { auth } from "@/lib/auth";
3import { redirect } from "next/navigation";
4
5export default async function AnalyticsPage() {
6  const session = await auth();
7
8  if (!session?.user) {
9    redirect("/auth/sign-in");
10  }
11
12  // Render protected content
13  return <AnalyticsDashboard user={session.user} />;
14}

[0x05] COMMON PATTERNS

User Avatar Display:

1<Avatar>
2  <AvatarImage src={session.user.image ?? undefined} />
3  <AvatarFallback>
4    {session.user.name?.charAt(0).toUpperCase()}
5  </AvatarFallback>
6</Avatar>

Sign Out Button:

1import { signOut } from "@/lib/auth";
2
3<form action={async () => {
4  "use server";
5  await signOut();
6}}>
7  <button type="submit">> SIGN OUT</button>
8</form>

Role-Based Access:

1const session = await auth();
2if (session?.user?.role !== "ADMIN") {
3  redirect("/dashboard");
4}
5
6// Render admin-only template
7return <AdminPanel />;

[0x06] TROUBLESHOOTING

[ERROR]: Session is null

Fix: User not authenticated or session expired. Redirect to sign-in page and verify NEXTAUTH_SECRET is set.

[ERROR]: useSession is not a function

Fix: Missing SessionProvider wrapper. Wrap app in <SessionProvider> in root layout.

[ERROR]: Middleware redirect loop

Fix: Sign-in page is protected by middleware. Exclude auth routes from middleware matcher.

[0x07] NEXT STEPS

Connect Prisma to store user data in database
Add Polar.sh for user subscriptions and payments
Customize templates to match your brand

1$# NextAuth Configuration

2$NEXTAUTH_URL="http://localhost:3000"

3$NEXTAUTH_SECRET="your-32-character-secret-here"

5$# OAuth Providers (optional)

6$GOOGLE_CLIENT_ID="your-google-client-id"

7$GOOGLE_CLIENT_SECRET="your-google-client-secret"

9$GITHUB_CLIENT_ID="your-github-client-id"

10$GITHUB_CLIENT_SECRET="your-github-client-secret"

1import { auth } from "@/lib/auth";

3export default async function DashboardPage() {

4 const session = await auth();

6 if (!session?.user) {

7 redirect("/auth/sign-in");

8 }

10 return (

11 <div>

12 <h1>Welcome, {session.user.name}!</h1>

13 <p>Email: {session.user.email}</p>

14 </div>

15 );

16}

1"use client";

3import { useSession } from "next-auth/react";

5export default function ProfileCard() {

6 const { data: session, status } = useSession();

8 if (status === "loading") {

9 return <div>Loading...</div>;

10 }

12 if (!session?.user) {

13 return <div>Not authenticated</div>;

14 }

16 return (

17 <div>

18 <h2>{session.user.name}</h2>

19 <p>{session.user.email}</p>

20 </div>

21 );

22}

1// middleware.ts (root level)

2export { auth as middleware } from "@/lib/auth";

4export const config = {

5 matcher: [

6 "/dashboard/:path*", // Protect all dashboard routes

7 "/settings/:path*", // Protect settings

8 "/api/user/:path*", // Protect user API routes

9 ],

10};

1// app/(dashboard)/analytics/page.tsx

2import { auth } from "@/lib/auth";

3import { redirect } from "next/navigation";

5export default async function AnalyticsPage() {

6 const session = await auth();

8 if (!session?.user) {

9 redirect("/auth/sign-in");

10 }

12 // Render protected content

13 return <AnalyticsDashboard user={session.user} />;

14}