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.
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
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
import { createClerkClient } from '@clerk/backend'
const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY! })
async function seedTestUsers() {
const users = [
{ emailAddress: ['admin@test.com'], password: 'test1234', firstName: 'Admin', lastName: 'User' },
{ emailAddress: ['member@test.com'], password: 'test1234', firstName: 'Member', lastName: 'User' },
]
for (const user of users) {
try {
await clerk.users.createUser(user)
console.log(`Created: ${user.emailAddress[0]}`)
} catch (err: any) {
if (err.status === 422) {
console.log(`Already exists: ${user.emailAddress[0]}`)
} else {
throw err
}
}
}
}
seedTestUsers()
Run with:
npx tsx scripts/seed-test-users.ts
Step 3: Configure Hot Reload
const nextConfig = {
experimental: {
},
serverExternalPackages: ['@clerk/backend'],
}
export default nextConfig
npx next dev --experimental-https
Step 4: Development Scripts
{
"scripts": {
"dev": "next dev",
"dev:https": "next dev --experimental-https",
"dev:seed": "tsx scripts/seed-test-users.ts",
"dev:tunnel": "ngrok http 3000",
"dev:webhook": "ngrok http 3000 --log stdout"
}
}
Step 5: Mock Authentication for Tests
import { vi } from 'vitest'
export function mockClerkAuth(overrides: { userId?: string; orgId?: string } = {}) {
const mockAuth = {
userId: overrides.userId || 'user_test_123',
orgId: overrides.orgId || null,
getToken: vi.fn().mockResolvedValue('mock_token'),
has: vi.fn().mockReturnValue(true),
}
vi.mock('@clerk/nextjs/server', () => ({
auth: vi.fn().mockResolvedValue(mockAuth),
currentUser: vi.fn().mockResolvedValue({
id: mockAuth.userId,
firstName: 'Test',
lastName: 'User',
emailAddresses: [{ emailAddress: 'test@test.com' }],
}),
clerkMiddleware: vi.fn(() => (req: any, : , : ) => ()),
}))
mockAuth
}
import { describe, it, expect, beforeEach } from 'vitest'
import { mockClerkAuth } from '../helpers/clerk-mock'
describe('GET /api/data', () => {
beforeEach(() => {
mockClerkAuth({ userId: 'user_test_123' })
})
it('returns data for authenticated user', async () => {
const res = await fetch('/api/data')
expect(res.status).toBe(200)
})
})
Output
- Development instance with test keys configured
- Test users seeded via script
- HTTPS dev server running for Clerk compatibility
- Vitest mock helpers for auth in unit tests
Error Handling
| Error | Cause | Solution |
|---|
| Dev/prod key mismatch | Using pk_live_ in dev | Switch to pk_test_ / sk_test_ keys |
| SSL required | Clerk needs HTTPS locally | Run next dev --experimental-https |
| Cookies not set | Wrong domain config | Check Clerk Dashboard domain settings |
| Session not persisting | Browser storage issue | Clear cookies, check localhost domain |
Examples
Playwright Auth Fixture for E2E Tests
import { test as base } from '@playwright/test'
export const test = base.extend({
authenticatedPage: async ({ page }, use) => {
await page.goto('/sign-in')
await page.fill('input[name="identifier"]', 'admin@test.com')
await page.click('button:has-text("Continue")')
await page.fill('input[name="password"]', 'test1234')
await page.click('button:has-text("Continue")')
await page.waitForURL('/dashboard')
await use(page)
},
})
Resources
Next Steps
Proceed to clerk-sdk-patterns for common SDK usage patterns.
