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

auth-components

Clerk Auth Components Skill

Overview

Available Scripts

1. Generate Authentication UI Pages

2. Customize Appearance and Theming

3. Validate Component Implementation

Available Templates

1. Sign-In Page Template

2. Sign-Up Page Template

3. Custom User Button Template

4. Protected Route Wrapper

Available Examples

1. Custom Sign-In with Clerk Elements

2. Social Authentication Buttons

3. Complete Theme Configuration

Appearance Customization Guide

1. Appearance Prop Structure

2. Global vs Component-Level Theming

3. Tailwind CSS v4 Integration

4. Element Targeting

Security Compliance

Best Practices

Requirements

Progressive Disclosure

Similar Skills