clerk-prod-checklist

Production readiness checklist for Clerk deployment.Use when preparing to deploy, reviewing production configuration,or auditing Clerk implementation before launch.Trigger with phrases like "clerk production", "clerk deploy checklist","clerk go-live", "clerk launch ready".

⭐939stars🔀114forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive production readiness checklist for Clerk authentication deployments. It serves as an automated runbook to audit environment variables, security configurations, and webhook setups, ensuring a secure, high-performance, and error-free transition from development to production environments.

Use Cases

  • Pre-launch Audit: Systematically review your Clerk integration before a major release to ensure live API keys are correctly configured and test keys are removed.
  • Security Hardening: Implement production-grade middleware protection, CSP headers, and secure session management to safeguard user authentication flows.
  • Webhook Synchronization: Configure and validate production webhook endpoints and secrets to ensure reliable real-time data syncing between Clerk and your database.
  • Performance & Monitoring: Optimize middleware matchers and integrate error tracking (like Sentry) to maintain high uptime and fast response times for auth-related routes.
  • Environment Migration: Safely manage the transition of OAuth providers and domain settings from staging to a live production domain.
nameclerk-prod-checklist
description|
allowed-toolsRead, Write, Edit, Grep, Bash(npm:*)
version1.0.0
licenseMIT
authorJeremy Longshore <jeremy@intentsolutions.io>

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

Next Steps

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