Clerk Integration Skill

This skill provides patterns for integrating Clerk's fully managed authentication service into a Go/React stack.

Architectural Standards

1. Go Backend Integration (Session & Hydration)

• Middleware: Use clerk.WithSession() to inject the user's Clerk ID and metadata into the Go context.
• Hydration: Implement a SyncUser helper that pulls the full user object from Clerk's API using the clerk-sdk-go and updates your local DB if needed.
• Metadata: Use privateMetadata for sensitive backend-only fields (e.g., Stripe Customer ID) and publicMetadata for UI-facing attributes (e.g., User Role).

2. Reliable Webhooks (Svix)

• Verification: Always verify Clerk webhooks using the svix package to prevent spoofing.
• Idempotency: Webhooks can be delivered multiple times. Ensure your DB handlers are idempotent using a webhook_id table or check-before-update logic.
• Events: Prioritize handling user.created, user.updated, and session.ended.

3. React Frontend Excellence

• Custom UI: While Clerk components are great, use useClerk() and useAuth() to build custom branded login flows for higher-tier enterprise feel.
• TanStack Query: