Tutorial: Authentication Setup | Bootspring Docs

Add complete user authentication to your Next.js app using Bootspring and Clerk.

What You'll Build#

Sign-in and sign-up pages
Protected routes
User session management
Profile dropdown

Prerequisites#

Next.js 14 project with App Router
Bootspring initialized
Clerk account (free tier works)

Time Required#

Approximately 20 minutes.

Step 1: Set Up Clerk#

Create a Clerk Application#

Go to clerk.com and sign up
Create a new application
Select authentication methods (Email, Google, GitHub)
Copy your API keys

Add Environment Variables#

# .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=/onboarding

Step 2: Apply the Auth Skill#

Use Bootspring's auth skill:

bootspring skill apply auth/clerk

This creates:

Middleware configuration
Sign-in page
Sign-up page
Auth layout

Step 3: Install Dependencies#

npm install @clerk/nextjs

Step 4: Configure the Provider#

Ask the auth-expert:

Set up ClerkProvider in the root layout with proper configuration.

Update your layout:

// app/layout.tsx
import { ClerkProvider } from '@clerk/nextjs';
import { Inter } from 'next/font/google';
import './globals.css';

const inter = Inter({ subsets: ['latin'] });

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body className={inter.className}>{children}</body>
      </html>
    </ClerkProvider>
  );
}

Step 5: Create Middleware#

Create the middleware:

// middleware.ts
import { authMiddleware } from '@clerk/nextjs';

export default authMiddleware({
  // Public routes that don't require authentication
  publicRoutes: [
    '/',
    '/sign-in(.*)',
    '/sign-up(.*)',
    '/api/webhooks(.*)',
    '/pricing',
    '/about',
  ],

  // Routes that can be accessed while signed out but
  // will have auth data if signed in
  ignoredRoutes: ['/api/public(.*)'],
});

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

Step 6: Create Auth Pages#

// app/(auth)/sign-in/[[...sign-in]]/page.tsx
import { SignIn } from '@clerk/nextjs';

export default function SignInPage() {
  return (
    <div className="flex min-h-screen items-center justify-center bg-gray-50">
      <SignIn
        appearance={{
          elements: {
            formButtonPrimary:
              'bg-blue-600 hover:bg-blue-700 text-sm normal-case',
          },
        }}
      />
    </div>
  );
}

// app/(auth)/sign-up/[[...sign-up]]/page.tsx
import { SignUp } from '@clerk/nextjs';

export default function SignUpPage() {
  return (
    <div className="flex min-h-screen items-center justify-center bg-gray-50">
      <SignUp
        appearance={{
          elements: {
            formButtonPrimary:
              'bg-blue-600 hover:bg-blue-700 text-sm normal-case',
          },
        }}
      />
    </div>
  );
}

Auth Layout#

// app/(auth)/layout.tsx
export default function AuthLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100">
      {children}
    </div>
  );
}

Step 7: Add User Button#

Ask the frontend-expert:

Create a header component with user button and navigation.

// components/Header.tsx
'use client';

import { UserButton, SignedIn, SignedOut, SignInButton } from '@clerk/nextjs';
import Link from 'next/link';

export function Header() {
  return (
    <header className="border-b bg-white">
      <div className="container mx-auto px-4 py-4 flex items-center justify-between">
        <Link href="/" className="text-xl font-bold">
          MyApp
        </Link>

        <nav className="flex items-center gap-6">
          <Link href="/features" className="text-gray-600 hover:text-gray-900">
            Features
          </Link>
          <Link href="/pricing" className="text-gray-600 hover:text-gray-900">
            Pricing
          </Link>

          <SignedIn>
            <Link
              href="/dashboard"
              className="text-gray-600 hover:text-gray-900"
            >
              Dashboard
            </Link>
            <UserButton afterSignOutUrl="/" />
          </SignedIn>

          <SignedOut>
            <SignInButton mode="modal">
              <button className="px-4 py-2 text-blue-600 hover:text-blue-700">
                Sign In
              </button>
            </SignInButton>
            <Link
              href="/sign-up"
              className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
            >
              Get Started
            </Link>
          </SignedOut>
        </nav>
      </div>
    </header>
  );
}

Step 8: Create Protected Routes#

Dashboard Layout#

// app/(dashboard)/layout.tsx
import { auth } from '@clerk/nextjs';
import { redirect } from 'next/navigation';
import { Sidebar } from '@/components/dashboard/Sidebar';

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const { userId } = auth();

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

  return (
    <div className="flex min-h-screen">
      <Sidebar />
      <main className="flex-1 p-8">{children}</main>
    </div>
  );
}

Dashboard Page#

// app/(dashboard)/dashboard/page.tsx
import { currentUser } from '@clerk/nextjs';

export default async function DashboardPage() {
  const user = await currentUser();

  return (
    <div>
      <h1 className="text-2xl font-bold mb-4">
        Welcome, {user?.firstName || 'User'}!
      </h1>
      <p className="text-gray-600">
        You're signed in as {user?.emailAddresses[0]?.emailAddress}
      </p>
    </div>
  );
}

Step 9: Sync Users to Database#

Create Webhook Endpoint#

Ask the backend-expert:

Create a Clerk webhook endpoint to sync users to our database.

// app/api/webhooks/clerk/route.ts
import { Webhook } from 'svix';
import { headers } from 'next/headers';
import { WebhookEvent } from '@clerk/nextjs/server';
import { prisma } from '@/lib/prisma';

export async function POST(req: Request) {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET;

  if (!WEBHOOK_SECRET) {
    throw new Error('Missing CLERK_WEBHOOK_SECRET');
  }

  const headerPayload = headers();
  const svix_id = headerPayload.get('svix-id');
  const svix_timestamp = headerPayload.get('svix-timestamp');
  const svix_signature = headerPayload.get('svix-signature');

  if (!svix_id || !svix_timestamp || !svix_signature) {
    return new Response('Missing svix headers', { status: 400 });
  }

  const payload = await req.json();
  const body = JSON.stringify(payload);

  const wh = new Webhook(WEBHOOK_SECRET);
  let evt: WebhookEvent;

  try {
    evt = wh.verify(body, {
      'svix-id': svix_id,
      'svix-timestamp': svix_timestamp,
      'svix-signature': svix_signature,
    }) as WebhookEvent;
  } catch (err) {
    console.error('Webhook verification failed:', err);
    return new Response('Verification failed', { status: 400 });
  }

  const eventType = evt.type;

  if (eventType === 'user.created') {
    const { id, email_addresses, first_name, last_name, image_url } = evt.data;

    await prisma.user.create({
      data: {
        clerkId: id,
        email: email_addresses[0]?.email_address,
        name: [first_name, last_name].filter(Boolean).join(' ') || null,
        avatarUrl: image_url,
      },
    });
  }

  if (eventType === 'user.updated') {
    const { id, email_addresses, first_name, last_name, image_url } = evt.data;

    await prisma.user.update({
      where: { clerkId: id },
      data: {
        email: email_addresses[0]?.email_address,
        name: [first_name, last_name].filter(Boolean).join(' ') || null,
        avatarUrl: image_url,
      },
    });
  }

  if (eventType === 'user.deleted') {
    const { id } = evt.data;

    await prisma.user.delete({
      where: { clerkId: id },
    });
  }

  return new Response('Webhook processed', { status: 200 });
}

Configure Webhook in Clerk#

Go to Clerk Dashboard → Webhooks
Create a new webhook
URL: https://yourdomain.com/api/webhooks/clerk
Select events: user.created, user.updated, user.deleted
Copy the signing secret to .env.local

CLERK_WEBHOOK_SECRET=whsec_...

Step 10: Test Your Setup#

Start your development server:

npm run dev
Visit http://localhost:3000
Click "Get Started" to sign up
Complete the sign-up flow
You should be redirected to /dashboard

Verification Checklist#

Sign-up works
Sign-in works
Protected routes redirect to sign-in
User button shows in header
Sign-out works
User synced to database

Security Review#

Run a quick security check:

bootspring agent invoke security-expert "Review the Clerk authentication setup"

The agent will verify:

Middleware configuration
Public routes are intentional
Webhook verification
Environment variables secure

What You Learned#

Setting up Clerk authentication
Creating protected routes
Using Clerk components
Syncing users to database
Webhook handling

Next Steps#

Troubleshooting#

Redirect Loop#

Check that your sign-in pages are in publicRoutes.

User Not Syncing#

Verify webhook URL is correct
Check webhook secret matches
Look at Clerk webhook logs

Middleware Not Working#

Ensure the matcher config includes your routes.