1# Clerk
2 
3Official docs:
4 
5- https://docs.convex.dev/auth/clerk
6- https://clerk.com/docs/guides/development/integrations/databases/convex
7 
8Use this when the app already uses Clerk or the user wants Clerk's hosted auth
9features.
10 
11## Workflow
12 
131. Confirm the user wants Clerk
142. Make sure the user has a Clerk account and a Clerk application
153. Determine the app framework:
16   - React
17   - Next.js
18   - TanStack Start
194. Ask whether the user wants local-only setup or production-ready setup now
205. Gather the Clerk keys and the Clerk Frontend API URL
216. Follow the correct framework section in the official docs
227. Complete the backend and client wiring
238. Verify Convex reports the user as authenticated after login
249. If the user wants production-ready setup, make sure the production Clerk
25   config is also covered
26 
27## What To Do
28 
29- Read the official Convex and Clerk guide before writing setup code
30- If the user does not already have Clerk set up, send them to
31  `https://dashboard.clerk.com/sign-up` to create an account and
32  `https://dashboard.clerk.com/apps/new` to create an application
33- Send the user to `https://dashboard.clerk.com/apps/setup/convex` if the Convex
34  integration is not already active
35- Match the guide to the app's framework, usually React, Next.js, or TanStack
36  Start
37- Use the official examples for `ConvexProviderWithClerk`, `ClerkProvider`, and
38  `useAuth`
39 
40## Key Setup Areas
41 
42- install the Clerk SDK for the framework in use
43- configure `convex/auth.config.ts` with the Clerk issuer domain
44- set the required Clerk environment variables
45- wrap the app with `ClerkProvider` and `ConvexProviderWithClerk`
46- use Convex auth-aware UI patterns such as `Authenticated`, `Unauthenticated`,
47  and `AuthLoading`
48 
49## Files and Env Vars To Expect
50 
51- `convex/auth.config.ts`
52- React or Vite client entry such as `src/main.tsx`
53- Next.js client wrapper for Convex if using App Router
54- Clerk account sign-up page: `https://dashboard.clerk.com/sign-up`
55- Clerk app creation page: `https://dashboard.clerk.com/apps/new`
56- Clerk Convex integration page: `https://dashboard.clerk.com/apps/setup/convex`
57- Clerk API keys page: `https://dashboard.clerk.com/last-active?path=api-keys`
58- Clerk environment variables:
59  - `CLERK_JWT_ISSUER_DOMAIN` for Convex backend validation in the Convex docs
60  - `CLERK_FRONTEND_API_URL` in the Clerk docs
61  - `VITE_CLERK_PUBLISHABLE_KEY` for Vite apps
62  - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` for Next.js apps
63  - `CLERK_SECRET_KEY` for Next.js server-side Clerk setup where required
64 
65`CLERK_JWT_ISSUER_DOMAIN` and `CLERK_FRONTEND_API_URL` refer to the same Clerk
66Frontend API URL value. Do not treat them as two different URLs.
67 
68## Concrete Steps
69 
701. If needed, create a Clerk account at `https://dashboard.clerk.com/sign-up`
712. If needed, create a Clerk application at
72   `https://dashboard.clerk.com/apps/new`
733. Open `https://dashboard.clerk.com/last-active?path=api-keys` and copy the
74   publishable key, plus the secret key for Next.js where needed
754. Open `https://dashboard.clerk.com/apps/setup/convex`
765. Activate the Convex integration in Clerk if it is not already active
776. Copy the Clerk Frontend API URL shown there
787. Install the Clerk package for the app's framework
798. Create or update `convex/auth.config.ts` so Convex validates Clerk tokens
809. Set the publishable key in the frontend environment
8110. Set the issuer domain or Frontend API URL so Convex can validate the JWT
8211. Replace plain `ConvexProvider` wiring with `ConvexProviderWithClerk`
8312. Wrap the app in `ClerkProvider`
8413. Use Convex auth helpers for authenticated rendering
8514. Run the normal Convex dev or deploy flow after updating backend auth config
8615. If the user wants production-ready setup, configure the production Clerk
87    values and production issuer domain too
88 
89## Gotchas
90 
91- Prefer `useConvexAuth()` over raw Clerk auth state when deciding whether
92  Convex-authenticated UI can render
93- For Next.js, keep server and client boundaries in mind when creating the
94  Convex provider wrapper
95- After changing `convex/auth.config.ts`, run the normal Convex dev or deploy
96  flow so the backend picks up the new config
97- Do not stop at "Clerk login works". The important check is that Convex also
98  sees the session and can authenticate requests.
99- If the repo already uses Clerk, preserve its existing auth flow unless the
100  user asked to change it.
101- Do not assume the same Clerk values work for both dev and production. Check
102  the production issuer domain and publishable key separately.
103- The Convex setup page is where you get the Clerk Frontend API URL for Convex.
104  Keep using the Clerk API keys page for the publishable key and the secret key.
105- If Convex says no auth provider matched the token, first confirm the Clerk
106  Convex integration was activated at
107  `https://dashboard.clerk.com/apps/setup/convex`
108- After activating the Clerk Convex integration, sign out completely and sign
109  back in before retesting. An old Clerk session can keep using a token that
110  Convex rejects.
111 
112## Production
113 
114- Ask whether the user wants dev-only setup or production-ready setup
115- If the answer is production-ready, make sure production Clerk keys and issuer
116  configuration are included
117- Verify production redirect URLs and any production Clerk domain values before
118  calling the task complete
119- Do not silently write a notes file into the repo by default. If the user wants
120  rollout or handoff docs, create one explicitly.
121 
122## Validation
123 
124- Verify the user can sign in with Clerk
125- If the Clerk integration was just activated, verify after a full Clerk
126  sign-out and fresh sign-in
127- Verify `useConvexAuth()` reaches the authenticated state after Clerk login
128- Verify protected Convex queries run successfully inside authenticated UI
129- Verify `ctx.auth.getUserIdentity()` is non-null in protected backend functions
130- If production-ready setup was requested, verify the production Clerk
131  configuration is also covered
132 
133## Checklist
134 
135- [ ] Confirm the user wants Clerk
136- [ ] Ask whether the user wants local-only setup or production-ready setup
137- [ ] Follow the correct framework section in the official guide
138- [ ] Set Clerk environment variables
139- [ ] Configure `convex/auth.config.ts`
140- [ ] Verify Convex authenticated state after login
141- [ ] If requested, configure the production deployment too
142