Clerk Environment Variables Reference

Overview
Core Variables
Domain Variables
Development vs Production
Security Considerations
Troubleshooting

Overview

This document provides a comprehensive reference for all Clerk environment variables used in the do.dev application. Environment variables control authentication behavior, domain configuration, and security settings.

Variable Categories

Core: Required for basic Clerk functionality
Domain: Domain configuration and routing
Routing: Define authentication flow URLs
Session: Configure session behavior
Security: Security and CORS settings
Development: Development-specific settings

Core Variables

Required Variables

`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`

Type: String
Required: Yes
Example: pk_test_Y29udmluY2luZy1yYXktNzIuY2xlcmsuYWNjb3VudHMuZGV2JA
Description: Public API key from Clerk Dashboard
Security: Safe to expose client-side
Location: The dodev application

# Development
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx

# Production
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxx

`CLERK_SECRET_KEY`

Type: String
Required: Yes
Example: sk_test_xxx...xxx
Description: Secret API key from Clerk Dashboard
Security: NEVER expose client-side or commit to version control
Location: The dodev application

# Development
CLERK_SECRET_KEY=sk_test_xxx

# Production
CLERK_SECRET_KEY=sk_live_xxx

Optional Core Variables

`CLERK_WEBHOOK_SECRET`

Type: String
Required: When using webhooks
Example: whsec_xxx...xxx
Description: Webhook signing secret for verifying webhook payloads
Security: Server-side only
Use Case: Syncing user data, handling events

CLERK_WEBHOOK_SECRET=whsec_xxx

Domain Variables

Variables for configuring the do.dev authentication domain.

Domain Configuration

`NEXT_PUBLIC_CLERK_IS_SATELLITE`

Type: Boolean
Required: No (defaults to false)
Value: false or omitted
Description: Marks application as single domain (not a satellite)

# For do.dev application - explicitly false or omitted
NEXT_PUBLIC_CLERK_IS_SATELLITE=false

`NEXT_PUBLIC_CLERK_DOMAIN`

Type: String
Required: Recommended
Example: do.dev or localhost:3005
Description: Application domain name
Use: Cookie domain and CORS configuration

# Development
NEXT_PUBLIC_CLERK_DOMAIN=localhost:3005

# Production
NEXT_PUBLIC_CLERK_DOMAIN=do.dev

Routing Configuration

`NEXT_PUBLIC_CLERK_SIGN_IN_URL`

Type: String
Required: Yes
Default: /sign-in
Description: Sign-in page route

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in

`NEXT_PUBLIC_CLERK_SIGN_UP_URL`

Type: String
Required: Yes
Default: /sign-up
Description: Sign-up page route

NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

`NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL`

Type: String
Required: No
Default: /
Description: Default redirect after sign-in
Use: When no return URL specified

NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/dashboard

`NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL`

Type: String
Required: No
Default: /
Description: Default redirect after sign-up
Use: Typically onboarding flow

NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/onboarding

Advanced Primary Variables

`CLERK_ALLOWED_REDIRECT_ORIGINS`

Type: Comma-separated string
Required: For additional allowed origins
Example: https://api.do.dev,https://admin.do.dev
Description: Allowed origins for cross-domain redirects
Security: Critical for preventing redirect attacks

# Development (if needed)
CLERK_ALLOWED_REDIRECT_ORIGINS=http://localhost:3000

# Production (if additional origins needed)
CLERK_ALLOWED_REDIRECT_ORIGINS=https://api.do.dev

Development vs Production

Development Configuration

# apps/dodev/.env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_CLERK_DOMAIN=localhost:3005
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/dashboard
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/onboarding

Production Configuration

# apps/dodev/.env.production
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxx
CLERK_SECRET_KEY=sk_live_xxx
NEXT_PUBLIC_CLERK_DOMAIN=do.dev
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/dashboard
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/onboarding

Environment File Hierarchy

dodev-project/
├── .env                    # Global defaults (never commit)
├── .env.local             # Local overrides (never commit)
└── apps/
    └── dodev/
        ├── .env       # App defaults (can commit non-secrets)
        ├── .env.local # Local overrides (never commit)
        └── .env.production # Production values (Vercel)

Security Considerations

Never Commit These Variables

# .gitignore
.env.local
.env.*.local
.env.production
.env.*.production

# Never commit these patterns
*_SECRET_KEY
*_WEBHOOK_SECRET
*_API_KEY

Environment Variable Validation

// utils/validateEnv.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 required Clerk environment variables: ${missing.join(', ')}`
    )
  }
  
  // Validate format
  if (!process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY?.startsWith('pk_')) {
    throw new Error('Invalid publishable key format')
  }
  
  if (!process.env.CLERK_SECRET_KEY?.startsWith('sk_')) {
    throw new Error('Invalid secret key format')
  }
}

Production Security Checklist

All secret keys stored in environment variables
No secrets in source code
Production keys different from development
HTTPS enforced for all production domains
CORS properly configured
Allowed redirect origins explicitly listed
Environment variables validated on startup
Secrets rotated regularly
Audit logs enabled

Troubleshooting

Common Issues

Missing Environment Variables

Error: "Missing publishable key"

# Check current environment
printenv | grep CLERK

# Verify .env.local exists and is loaded
cat .env.local

Wrong Environment

Issue: Using test keys in production

// Add environment check
if (process.env.NODE_ENV === 'production') {
  if (process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY?.includes('test')) {
    console.error('WARNING: Using test keys in production!')
  }
}

CORS Errors

Issue: Cross-origin requests blocked

# Add allowed origins if needed
CLERK_ALLOWED_REDIRECT_ORIGINS=https://api.do.dev

Debug Mode

Enable verbose logging for troubleshooting:

// Enable in development only
if (process.env.NODE_ENV === 'development') {
  // Log all Clerk-related env vars (except secrets)
  console.log('Clerk Configuration:', {
    publishableKey: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY?.substring(0, 10) + '...',
    domain: process.env.NEXT_PUBLIC_CLERK_DOMAIN,
    signInUrl: process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL,
    signUpUrl: process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL,
  })
}

Environment Variable Loading Order

System environment variables
.env file
.env.local file
.env.[NODE_ENV] file
.env.[NODE_ENV].local file
Runtime environment (Vercel, etc.)

Later sources override earlier ones.

Last Updated: January 2025 Maintained By: DevOps Team Review Schedule: Monthly