Configure Clerk for multiple environments (dev, staging, production).
Use when setting up environment-specific configurations,
managing multiple Clerk instances, or implementing environment promotion.
Trigger with phrases like "clerk environments", "clerk staging",
"clerk dev prod", "clerk multi-environment".
Configure Clerk across development, staging, and production environments with separate instances, environment-aware configuration, and safe promotion workflows.
Prerequisites
Clerk account (one instance per environment recommended)
CI/CD pipeline (GitHub Actions, Vercel, etc.)
Environment variable management in place
Instructions
Step 1: Create Clerk Instances
Create separate Clerk instances in the Dashboard for each environment:
// lib/clerk-config.ts
type ClerkEnv = 'development' | 'staging' | 'production'
function getClerkEnv(): ClerkEnv {
const key = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY || ''
if (key.startsWith('pk_live_')) return 'production'
if (process.env.VERCEL_ENV === 'preview') return 'staging'
return 'development'
}
export const clerkConfig = {
env: getClerkEnv(),
get isDev() { return this.env === 'development' },
get isProd() { return this.env === 'production' },
signInUrl: '/sign-in',
signUpUrl: '/sign-up',
afterSignInUrl: '/dashboard',
get allowedRedirectOrigins() {
switch (this.env) {
case 'production': return ['https://myapp.com']
case 'staging': return ['https://staging.myapp.com']
default: return ['http://localhost:3000']
}
},
}
Step 4: Startup Validation
// lib/validate-env.ts
export function validateClerkEnv() {
const required = [
'NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY',
'CLERK_SECRET_KEY',
]
const missing = required.filter((key) => !process.env[key])
if (missing.length > 0) {
throw new Error(`Missing Clerk env vars: ${missing.join(', ')}`)
}
const pk = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY!
const sk = process.env.CLERK_SECRET_KEY!
// Prevent key mismatch (test keys with live keys)
const pkIsLive = pk.startsWith('pk_live_')
const skIsLive = sk.startsWith('sk_live_')
if (pkIsLive !== skIsLive) {
throw new Error('Clerk key mismatch: publishable and secret keys must be from same environment')
}
// Warn if using live keys in development
if (pkIsLive && process.env.NODE_ENV === 'development') {
console.warn('WARNING: Using production Clerk keys in development mode')
}
}
Call at app startup:
// app/layout.tsx
import { validateClerkEnv } from '@/lib/validate-env'
validateClerkEnv()
Step 5: Webhook Configuration Per Environment
// app/api/webhooks/clerk/route.ts
import { headers } from 'next/headers'
import { Webhook } from 'svix'
export async function POST(req: Request) {
// Each environment uses its own webhook secret
const secret = process.env.CLERK_WEBHOOK_SECRET
if (!secret) {
console.error('CLERK_WEBHOOK_SECRET not configured for this environment')
return new Response('Server error', { status: 500 })
}
// Verification logic (same across environments)
const headerPayload = await headers()
const wh = new Webhook(secret)
const body = await req.text()
try {
const evt = wh.verify(body, {
'svix-id': headerPayload.get('svix-id')!,
'svix-timestamp': headerPayload.get('svix-timestamp')!,
'svix-signature': headerPayload.get('svix-signature')!,
})
// Handle event...
return new Response('OK', { status: 200 })
} catch {
return new Response('Invalid signature', { status: 400 })
}
}
