DO NOT upgrade any Clerk dependencies unless you’re following their official migration guide and understand the breaking changes. Upgrading without proper migration can break your authentication flow, webhooks, and user management. The current Clerk version in the boilerplate is tested and stable.
This guide covers working with Clerk for authentication in Titan. Titan already comes with a working webhook handler for Clerk authentication events that synchronizes user data with your database. See app/api/auth/webhook.ts for the implementation. When a user signs up or updates their profile in Clerk, the webhook will trigger and update your database accordingly, ensuring your user data stays in sync. We need to make sure we create these webhooks in Clerk (both for testing locally and in production)

​
Testing authentication locally

Assuming you have the ngrok url running, you can test the authentication flow locally.
  1. Set config.auth.enabled to true in config.ts
  2. Create a webhook in Clerk
a. Go to Configure -> Webhooks -> + Add Endpoint b. Set the Endpoint URL to [your-ngrok-url]/api/auth/webhook c. Set the Events to user.created and user.updated
  1. Run your app
bun run dev
  1. Test the authentication flow
When you successfully sign up with Clerk in your app, you should now successfully see the User added to your Clerk dashboard (Under the Users tab) and a new record created in your users table in Supabase ✅

​
Configuring authentication in production

You will need to create a new webhook in Clerk AND configure your production environment with the appropriate API keys.
  1. Create a Production Instance of your Clerk Application a. In your Clerk dashboard, create a new production application or switch your existing application to production mode b. Copy your Production API Keys:
    • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
    • CLERK_SECRET_KEY
    c. Setup the production webhook:
    • Go to Configure -> Webhooks -> + Add Endpoint
    • Set the Endpoint URL to https://[your-production-domain]/api/auth/webhook
    • Set the Events to user.created and user.updated
    • Copy the webhook secret for your environment variables
    You can use vercel’s default domain if you haven’t bought a custom domain yet.
    d. Configure Google Auth for your production application e. Connect your custom domain in the Clerk dashboard
  2. Update Environment Variables Ensure these environment variables are set in your production environment (e.g., Vercel): 
    CLERK_SECRET_KEY="Your production secret key"
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="Your production publishable key"
CLERK_WEBHOOK_SECRET="Your production webhook secret"
  3. Deploy Your Application
Update your production environment variables in Vercel to use your production Clerk keys and deploy your application.

​
Common Issues & Troubleshooting

To be updated soon…