clerk-environments-deployment

Clerk Environments, Deployment, and Multi-Language Checklists

Overview

Use this skill when the task is broader than a single framework: development vs production setup, deployment readiness, custom domains, DNS, redirects, CORS/cookies, webhooks, CSP, monitoring, incident response, or multi-language backend architecture.

Clerk integrations often work locally and fail in production because keys, domains, redirects, OAuth credentials, webhook secrets, proxy headers, or CSP are environment-specific. Treat environment design as part of the auth implementation, not a deployment afterthought.

Environment Model

Use separate Clerk instances for development and production. For staging/preview, decide explicitly whether to use a separate staging Clerk instance or a constrained development instance. Avoid sharing a production instance with untrusted preview URLs unless there is a strong reason and hardened allowlists.

Key prefixes are a fast sanity check:

Key type	Development	Production	Exposure
Publishable key	pk_test_...	pk_live_...	Client-safe
Secret key	sk_test_...	sk_live_...	Server-only
Webhook signing secret	whsec_...	whsec_... per endpoint/instance	Server-only
Encryption key	random secret	random secret	Server-only

Never mix pk_test_ with sk_live_, pk_live_ with sk_test_, or webhook secrets from another endpoint/instance.

Local Development Checklist

• Use .env.local/local secret storage for dev keys only.
• Confirm framework variable names: e.g. NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY for Next.js client exposure and CLERK_SECRET_KEY for server-only use.
• Configure local sign-in/sign-up routes and fallback redirects.
• Use the Clerk CLI where useful: setup/init, env pull, and deploy status checks.
• For webhooks, expose the local app with a tunnel and create a development webhook endpoint using the tunnel URL.
• Keep local webhook signing secrets separate from production secrets.
• Test signed-out, signed-in, wrong-role, wrong-org, and webhook replay flows locally.
• Do not commit .env files, logs with tokens, or tunnel URLs that imply private infrastructure.
• Confirm NTP is enabled on the dev host and inside any Docker/WSL2 containers; clock drift causes spurious token-not-active-yet/token-expired errors. For container time resync recipes (WSL2 timedatectl, Docker Desktop restart, docker exec date -s), load the clerk-clock-skew-jwt skill.