Clerk Auth Components Skill

This skill provides comprehensive templates and patterns for implementing and customizing Clerk authentication components including pre-built components, Clerk Elements for custom flows, and appearance theming.

Overview

Clerk offers two approaches for authentication UI:

• Pre-built Components - Ready-to-use <SignIn /> , <SignUp /> , <UserButton /> with minimal configuration

• Clerk Elements - Custom components with granular control for advanced use-cases

This skill covers both approaches with practical templates and customization patterns.

Available Scripts

1. Generate Authentication UI Pages

Script: scripts/generate-auth-ui.sh <output-dir> <component-type>

Purpose: Generates complete authentication page templates

Component Types:

• signin

• SignIn page with routing

• signup

• SignUp page with routing

• both

• Both SignIn and SignUp pages

• profile

• User profile page

• all

• Complete auth UI set

Usage:

Generate sign-in page

./scripts/generate-auth-ui.sh ./app/sign-in signin

Generate both sign-in and sign-up

./scripts/generate-auth-ui.sh ./app signup

Generate complete auth UI

./scripts/generate-auth-ui.sh ./app all

Generated Files:

• app/sign-in/[[...sign-in]]/page.tsx

• app/sign-up/[[...sign-up]]/page.tsx

• app/profile/[[...profile]]/page.tsx

• components/auth/protected-wrapper.tsx

2. Customize Appearance and Theming

Script: scripts/customize-appearance.sh <config-file> <theme-preset>

Purpose: Generates appearance configuration for Clerk components

Theme Presets:

• default

• Clerk default theme

• dark

• Dark mode theme

• neobrutalist

• Neobrutalist theme

• shadesOfPurple

• Shades of Purple theme

• custom

• Custom theme template

Usage:

Generate dark theme config

./scripts/customize-appearance.sh ./lib/clerk-config.ts dark

Generate custom theme template

./scripts/customize-appearance.sh ./lib/clerk-config.ts custom

Generate theme with custom variables

BRAND_COLOR="#6366f1" ./scripts/customize-appearance.sh ./lib/clerk-config.ts custom

Environment Variables:

• BRAND_COLOR

• Primary brand color (hex)

• BACKGROUND

• Background color (hex)

• TEXT_COLOR

• Text color (hex)

3. Validate Component Implementation

Script: scripts/validate-components.sh <project-dir>

Purpose: Validates Clerk component setup and configuration

Checks:

• Clerk dependencies installed (@clerk/nextjs)

• Environment variables configured

• ClerkProvider setup in layout

• Authentication pages exist

• Middleware configured

• No hardcoded secrets

Usage:

Validate current project

./scripts/validate-components.sh .

Validate specific directory

./scripts/validate-components.sh /path/to/project

Exit Codes:

• 0 : Validation passed

• 1 : Validation failed (must fix issues)

Available Templates

1. Sign-In Page Template

Template: templates/sign-in-page.tsx

Features:

• Next.js App Router integration

• Catch-all routing [[...sign-in]]

• After sign-in redirect configuration

• Centered layout with responsive design

Usage:

// app/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"> <SignIn appearance={{ elements: { rootBox: "mx-auto", card: "shadow-lg" } }} afterSignInUrl="/dashboard" /> </div> ) }

2. Sign-Up Page Template

Template: templates/sign-up-page.tsx

Features:

• Next.js App Router integration

• Catch-all routing [[...sign-up]]

• After sign-up redirect configuration

• Custom appearance configuration

3. Custom User Button Template

Template: templates/user-button-custom.tsx

Features:

• Custom menu items

• Appearance customization

• Avatar size control

• Dropdown actions

Customization Example:

<UserButton appearance={{ elements: { userButtonAvatarBox: "w-10 h-10", userButtonPopoverCard: "shadow-xl" } }}

<UserButton.MenuItems> <UserButton.Link label="Dashboard" labelIcon={<LayoutDashboard size={16} />} href="/dashboard" /> <UserButton.Action label="Settings" labelIcon={<Settings size={16} />} onClick={() => router.push('/settings')} /> </UserButton.MenuItems> </UserButton>

4. Protected Route Wrapper

Template: templates/protected-wrapper.tsx

Features:

• Authentication guard for routes

• Loading states

• Redirect configuration

• Reusable HOC pattern

Usage:

// app/dashboard/page.tsx import { ProtectedRoute } from '@/components/auth/protected-wrapper'

export default function DashboardPage() { return ( <ProtectedRoute> <div>Protected Dashboard Content</div> </ProtectedRoute> ) }

Available Examples

1. Custom Sign-In with Clerk Elements

Example: examples/custom-sign-in-guide.md (code: examples/custom-sign-in.tsx )

Demonstrates:

• Clerk Elements for custom sign-in flow

• Step-based authentication

• Strategy selection (password, OAuth)

• Form validation

• Error handling

• Custom styling

Key Components:

<SignIn.Root> <SignIn.Step name="start"> {/* Email/username input /} <SignIn.Strategy name="password"> {/ Password input /} </SignIn.Strategy> <SignIn.Strategy name="email_code"> {/ Email verification */} </SignIn.Strategy> </SignIn.Step> </SignIn.Root>

2. Social Authentication Buttons

Example: examples/social-authentication-guide.md (code: examples/social-buttons.tsx )

Demonstrates:

• OAuth provider buttons

• Custom social button styling

• Loading states

• Error handling

• Multiple providers (Google, GitHub, Discord)

Supported Providers:

• Google

• GitHub

• Discord

• Microsoft

• Facebook

• Apple

3. Complete Theme Configuration

Example: examples/theming-guide.md (code: examples/theme-config.tsx )

Demonstrates:

• Complete appearance configuration

• CSS variables customization

• Layout configuration

• Element-specific styling

• Dark mode support

• Responsive design

Appearance Customization Guide

1. Appearance Prop Structure

The appearance prop accepts:

appearance={{ baseTheme: dark, // Base theme layout: { // Layout options shimmer: true, logoPlacement: 'inside' }, variables: { // CSS variables colorPrimary: '#6366f1', colorBackground: '#ffffff', colorText: '#1f2937', borderRadius: '0.5rem' }, elements: { // Element overrides card: 'shadow-lg', formButtonPrimary: 'bg-blue-500', footerActionLink: 'text-blue-600' } }}

2. Global vs Component-Level Theming

Global (ClerkProvider):

<ClerkProvider appearance={{ baseTheme: dark, variables: { colorPrimary: '#6366f1' } }}> {children} </ClerkProvider>

Component-Level:

<SignIn appearance={{ elements: { card: 'shadow-xl', rootBox: 'mx-auto' } }} />

3. Tailwind CSS v4 Integration

For Tailwind CSS v4 support:

<ClerkProvider appearance={{ cssLayerName: 'clerk' // Ensures Tailwind utilities override }}

4. Element Targeting

Common element selectors:

• rootBox

• Root container

• card

• Main card container

• headerTitle

• Header text

• formButtonPrimary

• Submit buttons

• formFieldInput

• Input fields

• footerActionLink

• Footer links

• userButtonAvatarBox

• User avatar

• userButtonPopoverCard

• Dropdown menu

Security Compliance

This skill follows strict security rules:

• All code examples use placeholder values only

• No real API keys, passwords, or secrets

• Environment variable references in all code

• .gitignore protection documented

• CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY read from environment

Best Practices

• Use Pre-built Components First - Start with <SignIn /> , <SignUp /> before custom Elements

• Apply Global Themes - Configure appearance at <ClerkProvider> level for consistency

• Leverage CSS Variables - Use variables prop for brand colors, spacing, and typography

• Element Overrides for Fine-Tuning - Use elements prop for specific component styling

• Protect Routes - Always wrap protected content in authentication checks

• Handle Loading States - Show loading indicators during authentication state checks

• Configure Redirects - Set afterSignInUrl and afterSignUpUrl for better UX

• Responsive Design - Test auth components on mobile and desktop viewports

Requirements

• Clerk account with API keys

• Next.js 13+ with App Router (for examples)

• React 18+

• Environment variables:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

• CLERK_SECRET_KEY

• Optional: @clerk/themes for pre-built themes

• Optional: Tailwind CSS for styling examples

Progressive Disclosure

For advanced customization patterns, see:

• examples/custom-sign-in.tsx

• Complete Clerk Elements implementation

• examples/social-buttons.tsx

• OAuth provider integration

• examples/theme-config.tsx

• Advanced theming patterns