Clerk Production Checklist
Overview
Complete checklist to ensure your Clerk integration is production-ready. Covers environment config, security hardening, monitoring, error handling, and compliance.
Prerequisites
- Clerk integration working in development
- Production environment and domain configured
- CI/CD pipeline ready
Instructions
Step 1: Environment Configuration Checklist
| Check | Status | Action |
|---|
Using pk_live_ keys | [ ] | Switch from test to live keys |
CLERK_SECRET_KEY is sk_live_ | [ ] | Never use test keys in production |
.env.local in .gitignore | [ ] | Prevent accidental secret commits |
CLERK_WEBHOOK_SECRET set | [ ] | Required for webhook verification |
| Production domain in Clerk Dashboard | [ ] | Dashboard > Domains |
| Sign-in/sign-up URLs configured | [ ] | Set NEXT_PUBLIC_CLERK_SIGN_IN_URL etc. |
Step 2: Validation Script
import { createClerkClient } from '@clerk/backend'
async function validateProduction() {
const checks: { name: string; pass: boolean; detail: string }[] = []
const pk = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY || ''
const sk = process.env.CLERK_SECRET_KEY || ''
checks.push({
name: 'Live publishable key',
pass: pk.startsWith('pk_live_'),
detail: pk.startsWith('pk_live_') ? 'Using live key' : `Using ${pk.slice(0, 8)}... (should be pk_live_)`,
})
checks.push({
name: 'Live secret key',
pass: sk.startsWith('sk_live_'),
detail: sk.startsWith('sk_live_') ? 'Using live key' : 'Should be sk_live_ for production',
})
try {
const clerk = createClerkClient({ secretKey: sk })
await clerk.users.getUserList({ limit: 1 })
checks.push({ name: 'API connectivity', pass: true, detail: 'Backend API reachable' })
} catch (err: any) {
checks.push({ name: 'API connectivity', pass: false, detail: err.message })
}
checks.push({
name: 'Webhook secret configured',
pass: !!process.env.CLERK_WEBHOOK_SECRET,
detail: process.env.CLERK_WEBHOOK_SECRET ? 'Set' : 'CLERK_WEBHOOK_SECRET missing',
})
const fs = await import('fs')
const hasMiddleware = fs.existsSync('middleware.ts') || fs.existsSync('src/middleware.ts')
checks.push({
name: 'Middleware present',
pass: hasMiddleware,
detail: hasMiddleware ? 'Found' : 'middleware.ts not found at project root',
})
console.log('\n=== Clerk Production Readiness ===\n')
for (const check of checks) {
const icon = check.pass ? 'PASS' : 'FAIL'
console.log(`[${icon}] ${check.name}: ${check.detail}`)
}
const allPass = checks.every((c) => c.pass)
console.log(`\nResult: ${allPass ? 'READY for production' : 'NOT READY — fix failing checks'}`)
process.exit(allPass ? 0 : 1)
}
validateProduction()
Run with:
npx tsx scripts/prod-readiness.ts
Step 3: Security Checklist
| Check | Status | Action |
|---|
| Middleware protects all routes | [ ] | Verify non-public routes require auth |
API routes check userId | [ ] | Return 401 if userId is null |
| Webhook signatures verified | [ ] | Use svix library for verification |
| CORS configured correctly | [ ] | Only allow production domain |
| Rate limiting on sensitive endpoints | [ ] | Use @upstash/ratelimit or similar |
| CSP headers set | [ ] | Add Clerk domains to Content-Security-Policy |
| No secret keys in client code | [ ] | CLERK_SECRET_KEY never exposed |
Step 4: Monitoring Checklist
| Check | Status | Action |
|---|
| Health check endpoint | [ ] | /api/health monitoring Clerk API |
| Error tracking (Sentry) | [ ] | Clerk user context in error reports |
| Auth event logging | [ ] | Log sign-in, sign-out, permission denied |
| Webhook monitoring | [ ] | Alert on failed webhook deliveries |
| Uptime monitoring | [ ] | External monitor hitting health endpoint |
Step 5: Error Handling Checklist
| Check | Status | Action |
|---|
| Custom error pages | [ ] | /not-found, /error pages handle auth errors |
| Graceful auth failures | [ ] | Redirect to sign-in, don't show stack traces |
| Webhook retry handling | [ ] | Idempotency keys prevent duplicate processing |
| Session expiry UX | [ ] | Show "session expired" prompt, not blank page |
'use client'
import { useAuth } from '@clerk/nextjs'
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
const { isSignedIn } = useAuth()
return (
<div>
<h2>Something went wrong</h2>
<p>{error.message}</p>
<button onClick={reset}>Try again</button>
{!isSignedIn && <a href="/sign-in">Sign in</a>}
</div>
)
}
Step 6: Performance Checklist
| Check | Status | Action |
|---|
| Middleware matcher excludes static files | [ ] | Don't auth-check images, fonts, CSS |
User data cached (React.cache()) | [ ] | Deduplicate within request |
| Auth components lazy loaded | [ ] | dynamic() for UserButton, SignInButton |
| Edge Runtime for middleware | [ ] | Faster cold starts on Vercel |
Output
- Environment configuration verified (live keys, webhook secret, domain)
- Automated validation script (run in CI or before deploy)
- Security, monitoring, error handling, and performance checklists
- Global error boundary component with auth context
Error Handling
| Error | Cause | Solution |
|---|
| Validation script fails | Test keys in production | Switch to pk_live_ / sk_live_ keys |
| API connectivity check fails | Wrong secret key | Verify key in Clerk Dashboard > API Keys |
| Middleware not found | File in wrong location | Place middleware.ts at project root (not inside app/) |
| Health check returns 503 | Clerk API unreachable | Check network, verify key, check status.clerk.com |
Examples
CI Production Gate
- name: Clerk production readiness
run: npx tsx scripts/prod-readiness.ts
env:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: ${{ secrets.CLERK_PK_PROD }}
CLERK_SECRET_KEY: ${{ secrets.CLERK_SK_PROD }}
CLERK_WEBHOOK_SECRET: ${{ secrets.CLERK_WEBHOOK_SECRET_PROD }}
Resources
Next Steps
Proceed to clerk-upgrade-migration for SDK version upgrades.
