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".
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.
| name | clerk-prod-checklist |
|---|---|
| description | | |
| allowed-tools | Read, Write, Edit, Grep, Bash(npm:*) |
| version | 1.0.0 |
| license | MIT |
| author | Jeremy 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.createduser.updateduser.deletedsession.createdsession.revokedorganization.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.