How to Sync Clerk Users to Supabase with Webhooks (TDD Approach)

The Problem Clerk handles authentication beautifully, but your app logic lives in Supabase. Every time a user signs up or updates their profile, you need a corresponding row in your users table. The solution: a Clerk webhook → /api/webhooks/clerk → upsert into Supabase. Red First: Write Failing Tests // src/lib/__tests__/auth-sync.test.ts describe("mapClerkUserToDb", () => { it("maps basic user fields", () => { const clerkUser = { id: "user_123", emailAddresses: [{ emailAddress: "[email protected]" }], firstName: "John", lastName: "Doe", }; const result = mapClerkUserToDb(clerkUser); expect(result).toEqual({ clerk_id: "user_123", email: "[email protected]", full_name: "John Doe", plan: "free", credits: 30, }); }); }); Tests fail first. That's the point. Green: Implement auth-sync.ts export function mapClerkUserToDb(clerkUser: ClerkUser): DbUser { const email = clerkUser.emailAddresses[0]?.emailAddress ?? ""; const firstName = clerkUser.firstName ?? ""; const lastName = clerkUser.la