Clerk Production Checklist

Overview

Complete checklist to ensure your Clerk integration is production-ready.

Prerequisites

• Clerk integration working in development
• Production environment configured
• Domain and hosting ready

Production Checklist

1. Environment Configuration

API Keys

• Switch from test keys (pk_test_, sk_test_) to live keys (pk_live_, sk_live_)
• Store secret key in secure secrets manager (not environment files)
• Remove any hardcoded keys from codebase

# Verify production keys
echo "Publishable key starts with: ${NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY:0:8}"
# Should output: pk_live_

Environment Variables

# Required production variables
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...
CLERK_WEBHOOK_SECRET=whsec_...

# Optional but recommended
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

2. Clerk Dashboard Configuration

Domain Settings

• Add production domain in Clerk Dashboard
• Configure allowed origins for CORS
• Set up custom domain for Clerk (optional)

Authentication Settings

• Review and configure allowed sign-in methods
• Configure password requirements
• Set session token lifetime
• Configure multi-session behavior

OAuth Providers

• Switch OAuth apps to production mode
• Update redirect URLs to production domain
• Verify OAuth scopes are minimal needed

3. Security Configuration

Middleware

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

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

export default clerkMiddleware(async (auth, request) => {
  if (!isPublicRoute(request)) {
    await auth.protect()
  }
})

Security Headers

• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Strict-Transport-Security enabled
• Content-Security-Policy configured

4. Webhooks Setup

• Configure production webhook endpoint
• Set webhook secret in environment
• Subscribe to required events:
  • user.created
  • user.updated
  • user.deleted
  • session.created
  • session.revoked
  • organization.created (if using orgs)

// Verify webhook endpoint is accessible
// POST https://yourdomain.com/api/webhooks/clerk

5. Error Handling

• Custom error pages configured
• Error logging to monitoring service
• Fallback UI for auth failures

// app/error.tsx
'use client'

export default function Error({ error, reset }: {
  error: Error
  reset: () => void
}) {
  return (
    <div>
      <h2>Authentication Error</h2>
      <p>{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  )
}

6. Performance Optimization

• Enable ISR/SSG where possible
• Configure CDN caching headers
• Implement user data caching
• Optimize middleware matcher

// Optimized middleware matcher
export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)'
  ]
}

7. Monitoring & Logging

• Error tracking configured (Sentry, etc.)
• Authentication events logged
• Rate limit monitoring
• Uptime monitoring for auth endpoints

// Example: Sentry integration
import * as Sentry from '@sentry/nextjs'

export async function POST(request: Request) {
  try {
    // ... auth logic
  } catch (error) {
    Sentry.captureException(error, {
      tags: { component: 'clerk-auth' }
    })
    throw error
  }
}

8. Testing

• E2E tests for sign-in/sign-up flows
• API route authentication tests
• Webhook handling tests
• Load testing completed

// Example: Playwright test
test('user can sign in', async ({ page }) => {
  await page.goto('/sign-in')
  await page.fill('input[name="email"]', 'test@example.com')
  await page.fill('input[name="password"]', 'password123')
  await page.click('button[type="submit"]')
  await expect(page).toHaveURL('/dashboard')
})

9. Documentation

• Document environment variable requirements
• Document webhook event handling
• Document custom authentication flows
• Runbook for auth-related incidents

10. Backup & Recovery

• Understand Clerk's data retention
• Document user export procedures
• Plan for Clerk service disruption

Validation Script

#!/bin/bash
# scripts/validate-production.sh

echo "=== Clerk Production Validation ==="

# Check environment
if [[ $NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY != pk_live_* ]]; then
  echo "ERROR: Not using production publishable key"
  exit 1
fi

if [[ -z "$CLERK_SECRET_KEY" ]]; then
  echo "ERROR: CLERK_SECRET_KEY not set"
  exit 1
fi

if [[ -z "$CLERK_WEBHOOK_SECRET" ]]; then
  echo "WARNING: CLERK_WEBHOOK_SECRET not set"
fi

# Check middleware exists
if [[ ! -f "middleware.ts" ]]; then
  echo "WARNING: middleware.ts not found"
fi

echo "=== Validation Complete ==="

Output

• Complete production configuration
• Security hardening applied
• Monitoring configured
• Testing completed

Resources

• Clerk Production Checklist
• Security Best Practices
• Performance Guide

Next Steps

Proceed to clerk-upgrade-migration for SDK version upgrades.