From clerk-pack
Sets up Clerk local dev workflow: dev instance config, test user seeding, hot reload in Next.js, and npm scripts for HTTPS/tunneling. Use for local auth testing.
How this skill is triggered — by the user, by Claude, or both
Slash command
/clerk-pack:clerk-local-dev-loopThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Configure an efficient local development workflow with Clerk authentication, including test users, hot reload, and mock auth for unit tests.
Configure an efficient local development workflow with Clerk authentication, including test users, hot reload, and mock auth for unit tests.
clerk-install-auth completed)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:
// 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: ['[email protected]'], password: 'test1234', firstName: 'Admin', lastName: 'User' },
{ emailAddress: ['[email protected]'], 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
// 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
# Start dev server with HTTPS (required for some Clerk features)
npx next dev --experimental-https
// 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"
}
}
// 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: '[email protected]' }],
}),
clerkMiddleware: vi.fn(() => (req: any, res: any, next: any) => next()),
}))
return mockAuth
}
// 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)
})
})
| 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 |
// 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"]', '[email protected]')
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)
},
})
Proceed to clerk-sdk-patterns for common SDK usage patterns.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin clerk-packInstalls Clerk SDK and configures authentication for Next.js, React, or Express apps. Sets up env vars, ClerkProvider, middleware, and verifies initial auth.
Sets up Clerk authentication in projects using the Clerk CLI. Handles app creation, key provisioning, and environment configuration for multiple frameworks.
Comprehensive testing and validation tools for Clerk authentication integrations. Includes E2E auth flow testing, security audits, configuration validation, unit testing patterns for sign-in/sign-up flows. Use when implementing Clerk tests, validating authentication setup, testing auth flows, running security audits, creating E2E tests for Clerk, or when user mentions Clerk testing, auth validation, E2E authentication tests, security audit, or test coverage.