# Clerk

Official docs:

- https://docs.convex.dev/auth/clerk
- https://clerk.com/docs/guides/development/integrations/databases/convex

Use this when the app already uses Clerk or the user wants Clerk's hosted auth
features.

## Workflow

1. Confirm the user wants Clerk
2. Make sure the user has a Clerk account and a Clerk application
3. Determine the app framework:
   - React
   - Next.js
   - TanStack Start
4. Ask whether the user wants local-only setup or production-ready setup now
5. Gather the Clerk keys and the Clerk Frontend API URL
6. Follow the correct framework section in the official docs
7. Complete the backend and client wiring
8. Verify Convex reports the user as authenticated after login
9. If the user wants production-ready setup, make sure the production Clerk
   config is also covered

## What To Do

- Read the official Convex and Clerk guide before writing setup code
- If the user does not already have Clerk set up, send them to
  `https://dashboard.clerk.com/sign-up` to create an account and
  `https://dashboard.clerk.com/apps/new` to create an application
- Send the user to `https://dashboard.clerk.com/apps/setup/convex` if the Convex
  integration is not already active
- Match the guide to the app's framework, usually React, Next.js, or TanStack
  Start
- Use the official examples for `ConvexProviderWithClerk`, `ClerkProvider`, and
  `useAuth`

## Key Setup Areas

- install the Clerk SDK for the framework in use
- configure `convex/auth.config.ts` with the Clerk issuer domain
- set the required Clerk environment variables
- wrap the app with `ClerkProvider` and `ConvexProviderWithClerk`
- use Convex auth-aware UI patterns such as `Authenticated`, `Unauthenticated`,
  and `AuthLoading`

## Files and Env Vars To Expect

- `convex/auth.config.ts`
- React or Vite client entry such as `src/main.tsx`
- Next.js client wrapper for Convex if using App Router
- Clerk account sign-up page: `https://dashboard.clerk.com/sign-up`
- Clerk app creation page: `https://dashboard.clerk.com/apps/new`
- Clerk Convex integration page: `https://dashboard.clerk.com/apps/setup/convex`
- Clerk API keys page: `https://dashboard.clerk.com/last-active?path=api-keys`
- Clerk environment variables:
  - `CLERK_JWT_ISSUER_DOMAIN` for Convex backend validation in the Convex docs
  - `CLERK_FRONTEND_API_URL` in the Clerk docs
  - `VITE_CLERK_PUBLISHABLE_KEY` for Vite apps
  - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` for Next.js apps
  - `CLERK_SECRET_KEY` for Next.js server-side Clerk setup where required

`CLERK_JWT_ISSUER_DOMAIN` and `CLERK_FRONTEND_API_URL` refer to the same Clerk
Frontend API URL value. Do not treat them as two different URLs.

## Concrete Steps

1. If needed, create a Clerk account at `https://dashboard.clerk.com/sign-up`
2. If needed, create a Clerk application at
   `https://dashboard.clerk.com/apps/new`
3. Open `https://dashboard.clerk.com/last-active?path=api-keys` and copy the
   publishable key, plus the secret key for Next.js where needed
4. Open `https://dashboard.clerk.com/apps/setup/convex`
5. Activate the Convex integration in Clerk if it is not already active
6. Copy the Clerk Frontend API URL shown there
7. Install the Clerk package for the app's framework
8. Create or update `convex/auth.config.ts` so Convex validates Clerk tokens
9. Set the publishable key in the frontend environment
10. Set the issuer domain or Frontend API URL so Convex can validate the JWT
11. Replace plain `ConvexProvider` wiring with `ConvexProviderWithClerk`
12. Wrap the app in `ClerkProvider`
13. Use Convex auth helpers for authenticated rendering
14. Run the normal Convex dev or deploy flow after updating backend auth config
15. If the user wants production-ready setup, configure the production Clerk
    values and production issuer domain too

## Gotchas

- Prefer `useConvexAuth()` over raw Clerk auth state when deciding whether
  Convex-authenticated UI can render
- For Next.js, keep server and client boundaries in mind when creating the
  Convex provider wrapper
- After changing `convex/auth.config.ts`, run the normal Convex dev or deploy
  flow so the backend picks up the new config
- Do not stop at "Clerk login works". The important check is that Convex also
  sees the session and can authenticate requests.
- If the repo already uses Clerk, preserve its existing auth flow unless the
  user asked to change it.
- Do not assume the same Clerk values work for both dev and production. Check
  the production issuer domain and publishable key separately.
- The Convex setup page is where you get the Clerk Frontend API URL for Convex.
  Keep using the Clerk API keys page for the publishable key and the secret key.
- If Convex says no auth provider matched the token, first confirm the Clerk
  Convex integration was activated at
  `https://dashboard.clerk.com/apps/setup/convex`
- After activating the Clerk Convex integration, sign out completely and sign
  back in before retesting. An old Clerk session can keep using a token that
  Convex rejects.

## Production

- Ask whether the user wants dev-only setup or production-ready setup
- If the answer is production-ready, make sure production Clerk keys and issuer
  configuration are included
- Verify production redirect URLs and any production Clerk domain values before
  calling the task complete
- Do not silently write a notes file into the repo by default. If the user wants
  rollout or handoff docs, create one explicitly.

## Validation

- Verify the user can sign in with Clerk
- If the Clerk integration was just activated, verify after a full Clerk
  sign-out and fresh sign-in
- Verify `useConvexAuth()` reaches the authenticated state after Clerk login
- Verify protected Convex queries run successfully inside authenticated UI
- Verify `ctx.auth.getUserIdentity()` is non-null in protected backend functions
- If production-ready setup was requested, verify the production Clerk
  configuration is also covered

## Checklist

- [ ] Confirm the user wants Clerk
- [ ] Ask whether the user wants local-only setup or production-ready setup
- [ ] Follow the correct framework section in the official guide
- [ ] Set Clerk environment variables
- [ ] Configure `convex/auth.config.ts`
- [ ] Verify Convex authenticated state after login
- [ ] If requested, configure the production deployment too
