Ctrl + K

clerk-local-dev-loop

tessl install github:jeremylongshore/claude-code-plugins-plus-skills --skill clerk-local-dev-loop

github.com/jeremylongshore/claude-code-plugins-plus-skills

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".

Review Score

81%

Validation Score

12/16

Implementation Score

73%

Activation Score

90%

Clerk Local Dev Loop

Overview

Configure an efficient local development workflow with Clerk authentication.

Prerequisites

Clerk SDK installed
Development and production instances in Clerk dashboard
Node.js development environment

Instructions

Step 1: Configure Development Instance

# Use development keys in .env.local
cat > .env.local << 'EOF'
# Development keys (start with pk_test_ and sk_test_)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# Optional: Custom sign-in/sign-up URLs
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding
EOF

Step 2: Set Up Test Users

// scripts/create-test-user.ts
// Use Clerk Backend SDK for test user management
import { clerkClient } from '@clerk/nextjs/server'

async function createTestUser() {
  const user = await clerkClient.users.createUser({
    emailAddress: ['test@example.com'],
    password: 'testpassword123',
    firstName: 'Test',
    lastName: 'User'
  })
  console.log('Created test user:', user.id)
}

Step 3: Configure Hot Reload

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Clerk works with fast refresh out of the box
  reactStrictMode: true,

  // Environment-specific configuration
  env: {
    CLERK_DOMAIN: process.env.NODE_ENV === 'development'
      ? 'clerk.your-dev-domain.com'
      : 'clerk.your-prod-domain.com'
  }
}

module.exports = nextConfig

Step 4: Development Scripts

{
  "scripts": {
    "dev": "next dev",
    "dev:https": "next dev --experimental-https",
    "clerk:dev": "npx @clerk/cli dev",
    "test:auth": "node scripts/test-auth.js"
  }
}

Step 5: Mock Authentication for Tests

// __tests__/setup.ts
import { vi } from 'vitest'

// Mock Clerk for unit tests
vi.mock('@clerk/nextjs', () => ({
  auth: () => ({ userId: 'test-user-id' }),
  currentUser: () => ({
    id: 'test-user-id',
    firstName: 'Test',
    emailAddresses: [{ emailAddress: 'test@example.com' }]
  }),
  useUser: () => ({
    user: { id: 'test-user-id', firstName: 'Test' },
    isLoaded: true,
    isSignedIn: true
  })
}))

Output

Development environment configured
Test users available
Hot reload working with auth
Mocked auth for testing

Error Handling

Error	Cause	Solution
Development/Production mismatch	Using prod keys in dev	Use pk_test_/sk_test_ keys locally
SSL Required	Clerk needs HTTPS	Use `next dev --experimental-https`
Cookies Not Set	Wrong domain config	Check Clerk dashboard domain settings
Session Not Persisting	LocalStorage issues	Clear browser storage, check domain

Examples

Environment Switching

// lib/clerk.ts
export const clerkConfig = {
  publishableKey: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY!,
  signInUrl: process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL || '/sign-in',
  signUpUrl: process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '/sign-up',
}

// Validate configuration
if (!clerkConfig.publishableKey.startsWith('pk_')) {
  throw new Error('Invalid Clerk publishable key')
}

Local Webhook Testing

# Use ngrok or similar for webhook testing
npx ngrok http 3000

# Update webhook URL in Clerk dashboard to ngrok URL
# https://abc123.ngrok.io/api/webhooks/clerk

Resources

Next Steps

Proceed to clerk-sdk-patterns for common SDK usage patterns.