clerk-local-dev-loop

# 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. ```bash # .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 ```typescript // 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: ['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: ```bash npx tsx scripts/seed-test-users.ts ``` ### Step 3: Configure Hot Reload ```typescript // next.config.ts — ensure Clerk works with hot reload const nextConfig = { // Clerk SDK is compatible with Turbopack experimental: { // turbo: {}, // Uncomment if using Turbopack }, // Prevent Clerk SDK from being bundled incorrectly serverExternalPackages: ['@clerk/backend'], } export default nextConfig ``` ```bash # Start dev server with HTTPS (required for some Clerk features) npx next dev --experimental-https ``` ### Step 4: Development Scripts ```json // package.json 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 ```typescript // test/helpers/clerk-mock.ts 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, res: any, next: any) => next()), })) return mockAuth } ``` ```typescript // test/api/data.test.ts 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 ```typescript // e2e/fixtures/auth.ts 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 - [Clerk Development Mode](https://clerk.com/docs/deployments/overview) - [Clerk Testing Guide](https://clerk.com/docs/testing/overview) - [Next.js HTTPS Dev](https://nextjs.org/docs/app/api-reference/cli/next#https-for-local-development) ## Next Steps Proceed to `clerk-sdk-patterns` for common SDK usage patterns.