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:

1. Pre-built Components - Ready-to-use <SignIn />, <SignUp />, <UserButton /> with minimal configuration
2. 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

1. Use Pre-built Components First - Start with <SignIn />, <SignUp /> before custom Elements
2. Apply Global Themes - Configure appearance at <ClerkProvider> level for consistency
3. Leverage CSS Variables - Use variables prop for brand colors, spacing, and typography
4. Element Overrides for Fine-Tuning - Use elements prop for specific component styling
5. Protect Routes - Always wrap protected content in authentication checks
6. Handle Loading States - Show loading indicators during authentication state checks
7. Configure Redirects - Set afterSignInUrl and afterSignUpUrl for better UX
8. 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