Clerk Setup (Authentication)

NextGenKit uses Clerk v7 for authentication, organizations, and RBAC.

1. Create a Clerk Application

  1. Go to dashboard.clerk.com
  2. Create a new application
  3. Enable the sign-in methods you want (email, Google, GitHub, etc.)
  4. Copy your Publishable Key and Secret Key to .env.local

2. Enable Organizations

  1. In Clerk Dashboard → Organizations → Enable
  2. Configure roles (admin, member) under Organization Settings

3. Set Up ngrok for Local Development

Clerk webhooks need a publicly accessible URL. Use ngrok to expose your local server:

# Install ngrok (macOS)
brew install ngrok

# Authenticate (one-time setup)
ngrok config add-authtoken YOUR_AUTH_TOKEN

# Start the tunnel
ngrok http 3000

Copy the https://xxxx.ngrok-free.app URL — you'll use this as your webhook endpoint.

4. Set Up Webhooks

  1. Go to Webhooks in Clerk Dashboard
  2. Add endpoint: https://xxxx.ngrok-free.app/api/webhooks/clerk
  3. Subscribe to events:
    • user.created
    • user.updated
    • organization.created
    • organizationMembership.created
  4. Copy the Signing Secret to CLERK_WEBHOOK_SIGNING_SECRET in .env.local

5. Production Webhook URL

When you deploy your app, update the webhook endpoint in Clerk Dashboard to your production URL:

https://your-domain.com/api/webhooks/clerk

Replace the ngrok URL with your actual deployed domain. You can keep the ngrok endpoint as a separate webhook for local development, or remove it entirely.

Key Conventions

  • Clerk v7 uses <Show when="signed-in"> instead of <SignedIn>
  • Auth guards live in lib/auth.ts — requireUser(), requireOrg(), requireRole()
  • Middleware is in proxy.ts (Next.js 16 convention)