Name: Clerk Prod Checklist
Author: jeremylongshore

스킬 검색.../

Clerk Prod Checklist | Skills Pool

// scripts/prod-readiness.ts
import { createClerkClient } from '@clerk/backend'

async function validateProduction() {
  const checks: { name: string; pass: boolean; detail: string }[] = []

  // 1. Live keys check
  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',
  })

  // 2. API connectivity
  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 })
  }

  // 3. Webhook secret
  checks.push({
    name: 'Webhook secret configured',
    pass: !!process.env.CLERK_WEBHOOK_SECRET,
    detail: process.env.CLERK_WEBHOOK_SECRET ? 'Set' : 'CLERK_WEBHOOK_SECRET missing',
  })

  // 4. Middleware exists
  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',
  })

  // Print results
  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()

npx tsx scripts/prod-readiness.ts

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

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

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

// app/error.tsx — global error boundary with auth context
'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>
  )
}

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

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

# .github/workflows/deploy.yml — add as pre-deploy step
- 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 }}

Clerk Prod Checklist

Overview

Prerequisites

Instructions

Step 1: Environment Configuration Checklist

Clerk Prod Checklist

Overview

Prerequisites

Instructions

Step 1: Environment Configuration Checklist

Step 2: Validation Script

Step 3: Security Checklist

Step 4: Monitoring Checklist

Step 5: Error Handling Checklist

Step 6: Performance Checklist

Output

Error Handling

Examples

CI Production Gate

Resources

Next Steps

Ordercli

Deployment Patterns

Junta Leiloeiros

Persona Sales Ops

Eliza App Development

Ordercli

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`