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".
/plugin marketplace add jeremylongshore/claude-code-plugins-plus-skills/plugin install clerk-pack@claude-code-plugins-plusThis skill is limited to using the following tools:
Configure an efficient local development workflow with Clerk authentication.
# 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
// 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)
}
// 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
{
"scripts": {
"dev": "next dev",
"dev:https": "next dev --experimental-https",
"clerk:dev": "npx @clerk/cli dev",
"test:auth": "node scripts/test-auth.js"
}
}
// __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
})
}))
| 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 |
// 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')
}
# 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
Proceed to clerk-sdk-patterns for common SDK usage patterns.