Clerk Multi-Environment Setup

Overview

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:

Environment	Instance	Key Prefix	Domain
Development	my-app-dev	pk_test_ / sk_test_	localhost:3000
Staging	my-app-staging	pk_test_ / sk_test_	staging.myapp.com
Production	my-app-prod	pk_live_ / sk_live_	myapp.com

Step 2: Environment Configuration Files

# .env.local (development - git-ignored)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_dev...
CLERK_SECRET_KEY=sk_test_dev...
CLERK_WEBHOOK_SECRET=whsec_dev...

# .env.staging (staging)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_staging...
CLERK_SECRET_KEY=sk_test_staging...
CLERK_WEBHOOK_SECRET=whsec_staging...

# .env.production (production)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_prod...
CLERK_SECRET_KEY=sk_live_prod...
CLERK_WEBHOOK_SECRET=whsec_prod...

Step 3: Environment-Aware Configuration

// 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']
    }
  },
}