Clerk Prod ChecklistSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: clerk-prod-checklist
description: '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".

  '
allowed-tools: Read, Write, Edit, Grep, Bash(npm:*)
version: 1.15.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- clerk
- deployment
- audit
compatibility: Designed for Claude Code
---
# 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

```typescript
// 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()
```

Run with:

```bash
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 |

```typescript
// 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>
  )
}
```

### 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)
- Automa

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.