Clerk Authentication | Bootspring Docs

Battle-tested patterns for Clerk authentication in Next.js applications.

Overview#

Clerk provides a complete authentication solution with:

Pre-built UI components
Social login providers
Multi-factor authentication
User management dashboard
Webhook support

Prerequisites:

Clerk account and API keys
Next.js 14+ with App Router

Installation#

npm install @clerk/nextjs

# .env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard

Implementation#

Server-Side Auth Check#

// lib/auth.ts
import { auth } from '@clerk/nextjs/server'

export async function requireAuth() {
  const { userId } = await auth()

  if (!userId) {
    throw new Error('UNAUTHORIZED')
  }

  return userId
}

// Usage in Server Action
export async function myAction() {
  const userId = await requireAuth()
  // Continue with authenticated user
}

Protected Layout#

// app/(protected)/layout.tsx
import { auth } from '@clerk/nextjs/server'
import { redirect } from 'next/navigation'

export default async function ProtectedLayout({
  children
}: {
  children: React.ReactNode
}) {
  const { userId } = await auth()

  if (!userId) {
    redirect('/sign-in')
  }

  return <>{children}</>
}

Get Current User with Metadata#

// lib/auth.ts
import { currentUser } from '@clerk/nextjs/server'
import { prisma } from '@/lib/db'

export async function getCurrentUser() {
  const user = await currentUser()
  if (!user) return null

  // Get or create database user
  const dbUser = await prisma.user.upsert({
    where: { clerkId: user.id },
    update: {
      email: user.emailAddresses[0]?.emailAddress,
      name: `${user.firstName} ${user.lastName}`.trim()
    },
    create: {
      clerkId: user.id,
      email: user.emailAddresses[0]?.emailAddress ?? '',
      name: `${user.firstName} ${user.lastName}`.trim()
    }
  })

  return dbUser
}

Client-Side Auth Hook#

// hooks/use-user.ts
'use client'
import { useUser } from '@clerk/nextjs'

export function useCurrentUser() {
  const { user, isLoaded, isSignedIn } = useUser()

  return {
    user: isSignedIn ? user : null,
    isLoading: !isLoaded,
    isAuthenticated: isSignedIn
  }
}

Middleware Configuration#

// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  '/settings(.*)',
  '/api/user(.*)'
])

const isPublicRoute = createRouteMatcher([
  '/',
  '/sign-in(.*)',
  '/sign-up(.*)',
  '/api/webhooks(.*)'
])

export default clerkMiddleware(async (auth, req) => {
  if (isProtectedRoute(req)) {
    await auth.protect()
  }
})

export const config = {
  matcher: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)']
}

Usage Examples#

Server Component#

// app/dashboard/page.tsx
import { auth } from '@clerk/nextjs/server'
import { redirect } from 'next/navigation'

export default async function DashboardPage() {
  const { userId } = await auth()

  if (!userId) {
    redirect('/sign-in')
  }

  return <Dashboard userId={userId} />
}

Server Action#

// actions/profile.ts
'use server'

import { auth } from '@clerk/nextjs/server'
import { prisma } from '@/lib/db'

export async function updateProfile(formData: FormData) {
  const { userId } = await auth()

  if (!userId) {
    throw new Error('Unauthorized')
  }

  await prisma.user.update({
    where: { clerkId: userId },
    data: {
      name: formData.get('name') as string
    }
  })
}

Best Practices#

Always sync with database - Create a database user record to store app-specific data
Use middleware for route protection - Centralize auth checks in middleware
Handle loading states - Show loading UI while Clerk initializes on client
Set up webhooks - Listen for user.created, user.updated, user.deleted events
Use Server Components - Prefer server-side auth checks when possible

Session Management - Managing user sessions
RBAC - Role-based access control
Prisma - Database integration