clerk-local-dev-loop

name	clerk-local-dev-loop
description	Set up local development workflow with Clerk. Use when configuring development environment, testing auth locally, or setting up hot reload with Clerk. Trigger with phrases like "clerk local dev", "clerk development", "test clerk locally", "clerk dev environment".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
compatible-with	claude-code, codex, openclaw
tags	["saas","clerk","testing","authentication","workflow"]

Clerk Local Dev Loop

Overview

Configure an efficient local development workflow with Clerk authentication, including test users, hot reload, and mock auth for unit tests.

Prerequisites

• Clerk SDK installed (clerk-install-auth completed)
• Development instance created in Clerk Dashboard
• Node.js development environment

Instructions

Step 1: Configure Development Instance

Create a separate Clerk development instance to isolate test data from production.

# .env.local — use test keys (pk_test_ / sk_test_)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# Optional: Enable Clerk debug logging
CLERK_DEBUG=true

Clerk development instances provide:

• No email verification required
• Test phone numbers accepted
• Relaxed rate limits
• OAuth with test credentials

Step 2: Set Up Test Users

// scripts/seed-test-users.ts
import { createClerkClient } from '@clerk/backend'

const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY! })

async function seedTestUsers() {
  const users = [
    { emailAddress: ['[e-mail]'], password: 'test1234', firstName: 'Admin', lastName: 'User' },
    { emailAddress: ['[e-mail]'], password: 'test1234', firstName: 'Member', lastName:  },
  ]

   ( user  users) {
     {
       clerk..(user)
      .()
    }  (: ) {
       (err. === ) {
        .()
      }  {
         err
      }
    }
  }
}

()