initial commit
This commit is contained in:
Matthias
188
.agents/skills/convex-setup-auth/references/convex-auth.md
Normal file
188
.agents/skills/convex-setup-auth/references/convex-auth.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Convex Auth
|
||||
|
||||
Official docs: https://docs.convex.dev/auth/convex-auth Setup guide:
|
||||
https://labs.convex.dev/auth/setup
|
||||
|
||||
Use this when the user wants auth handled directly in Convex rather than through
|
||||
a third-party provider.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Confirm the user wants Convex Auth specifically
|
||||
2. Determine which sign-in methods the app needs:
|
||||
- magic links or OTPs
|
||||
- OAuth providers
|
||||
- passwords and password reset
|
||||
3. Ask whether the user wants local-only setup or production-ready setup now
|
||||
4. Read the Convex Auth setup guide before writing code
|
||||
5. Make sure the project has a configured Convex deployment:
|
||||
- run `npx convex dev` first if `CONVEX_DEPLOYMENT` is not set
|
||||
- if CLI configuration requires interactive human input, stop and ask the
|
||||
user to complete that step before continuing
|
||||
6. Install the auth packages:
|
||||
- `npm install @convex-dev/auth @auth/core@0.37.0`
|
||||
7. Run the initialization command:
|
||||
- `npx @convex-dev/auth`
|
||||
8. Confirm the initializer created:
|
||||
- `convex/auth.config.ts`
|
||||
- `convex/auth.ts`
|
||||
- `convex/http.ts`
|
||||
9. Add the required `authTables` to `convex/schema.ts`
|
||||
10. Replace plain `ConvexProvider` wiring with `ConvexAuthProvider`
|
||||
11. Configure at least one auth method in `convex/auth.ts`
|
||||
12. Run `npx convex dev --once` or the normal dev flow to push the updated
|
||||
schema and generated code
|
||||
13. Verify the client can sign in successfully
|
||||
14. Verify Convex receives authenticated identity in backend functions
|
||||
15. If the user wants production-ready setup, make sure the same auth setup is
|
||||
configured for the production deployment as well
|
||||
16. Only add a `users` table and `storeUser` flow if the app needs app-level
|
||||
user records inside Convex
|
||||
|
||||
## What This Reference Is For
|
||||
|
||||
- choosing Convex Auth as the default provider for a new Convex app
|
||||
- understanding whether the app wants magic links, OTPs, OAuth, or passwords
|
||||
- keeping the setup provider-specific while using the official Convex Auth docs
|
||||
for identity and authorization behavior
|
||||
|
||||
## What To Do
|
||||
|
||||
- Read the Convex Auth setup guide before writing setup code
|
||||
- Follow the setup flow from the docs rather than recreating it from memory
|
||||
- If the app is new, consider starting from the official starter flow instead of
|
||||
hand-wiring everything
|
||||
- Treat `npx @convex-dev/auth` as a required initialization step for existing
|
||||
apps, not an optional extra
|
||||
|
||||
## Concrete Steps
|
||||
|
||||
1. Install `@convex-dev/auth` and `@auth/core@0.37.0`
|
||||
2. Run `npx convex dev` if the project does not already have a configured
|
||||
deployment
|
||||
3. If `npx convex dev` blocks on interactive setup, ask the user explicitly to
|
||||
finish configuring the Convex deployment
|
||||
4. Run `npx @convex-dev/auth`
|
||||
5. Confirm the generated auth setup is present before continuing:
|
||||
- `convex/auth.config.ts`
|
||||
- `convex/auth.ts`
|
||||
- `convex/http.ts`
|
||||
6. Add `authTables` to `convex/schema.ts`
|
||||
7. Replace `ConvexProvider` with `ConvexAuthProvider` in the app entry
|
||||
8. Configure the selected auth methods in `convex/auth.ts`
|
||||
9. Run `npx convex dev --once` or the normal dev flow so the updated schema and
|
||||
auth files are pushed
|
||||
10. Verify login locally
|
||||
11. If the user wants production-ready setup, repeat the required auth
|
||||
configuration against the production deployment
|
||||
|
||||
## Expected Files and Decisions
|
||||
|
||||
- `convex/schema.ts`
|
||||
- frontend app entry such as `src/main.tsx` or the framework-equivalent provider
|
||||
file
|
||||
- generated Convex Auth setup produced by `npx @convex-dev/auth`
|
||||
- an existing configured Convex deployment, or the ability to create one with
|
||||
`npx convex dev`
|
||||
- `convex/auth.ts` starts with `providers: []` until the app configures actual
|
||||
sign-in methods
|
||||
|
||||
- Decide whether the user is creating a new app or adding auth to an existing
|
||||
app
|
||||
- For a new app, prefer the official starter flow instead of rebuilding setup by
|
||||
hand
|
||||
- Decide which auth methods the app needs:
|
||||
- magic links or OTPs
|
||||
- OAuth providers
|
||||
- passwords
|
||||
- Decide whether the user wants local-only setup or production-ready setup now
|
||||
- Decide whether the app actually needs a `users` table inside Convex, or
|
||||
whether provider identity alone is enough
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Do not assume a specific sign-in method. Ask which methods the app needs
|
||||
before wiring UI and backend behavior.
|
||||
- `npx @convex-dev/auth` is important because it initializes the auth setup,
|
||||
including the key material. Do not skip it when adding Convex Auth to an
|
||||
existing project.
|
||||
- `npx @convex-dev/auth` will fail if the project does not already have a
|
||||
configured `CONVEX_DEPLOYMENT`.
|
||||
- `npx convex dev` may require interactive setup for deployment creation or
|
||||
project selection. If that happens, ask the user explicitly for that human
|
||||
step instead of guessing.
|
||||
- `npx @convex-dev/auth` does not finish the whole integration by itself. You
|
||||
still need to add `authTables`, swap in `ConvexAuthProvider`, and configure at
|
||||
least one auth method.
|
||||
- A project can still build even if `convex/auth.ts` still has `providers: []`,
|
||||
so do not treat a successful build as proof that sign-in is fully configured.
|
||||
- Convex Auth does not mean every app needs a `users` table. If the app only
|
||||
needs authentication gates, `ctx.auth.getUserIdentity()` may be enough.
|
||||
- If the app is greenfield, starting from the official starter flow is usually
|
||||
better than partially recreating it by hand.
|
||||
- Do not stop at local dev setup if the user expects production-ready auth. The
|
||||
production deployment needs the auth setup too.
|
||||
- Keep provider-specific setup and Convex Auth authorization behavior in the
|
||||
official docs instead of inventing shared patterns from memory.
|
||||
|
||||
## Production
|
||||
|
||||
- Ask whether the user wants dev-only setup or production-ready setup
|
||||
- If the answer is production-ready, make sure the auth configuration is applied
|
||||
to the production deployment, not just the dev deployment
|
||||
- Verify production-specific redirect URLs, auth method configuration, and
|
||||
deployment settings 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.
|
||||
|
||||
## Human Handoff
|
||||
|
||||
If `npx convex dev` or deployment setup requires human input:
|
||||
|
||||
- stop and explain exactly what the user needs to do
|
||||
- say why that step is required
|
||||
- resume the auth setup immediately after the user confirms it is done
|
||||
|
||||
## Validation
|
||||
|
||||
- Verify the user can complete a sign-in flow
|
||||
- Offer to validate sign up, sign out, and sign back in with the configured auth
|
||||
method
|
||||
- If browser automation is available in the environment, you can do this
|
||||
directly
|
||||
- If browser automation is not available, give the user a short manual
|
||||
validation checklist instead
|
||||
- Verify `ctx.auth.getUserIdentity()` returns an identity in protected backend
|
||||
functions
|
||||
- Verify protected UI only renders after Convex-authenticated state is ready
|
||||
- Verify environment variables and redirect settings match the current app
|
||||
environment
|
||||
- Verify `convex/auth.ts` no longer has an empty `providers: []` configuration
|
||||
once the app is meant to support real sign-in
|
||||
- Run `npx convex dev --once` or the normal dev flow after setup changes and
|
||||
confirm Convex codegen and push succeed
|
||||
- If production-ready setup was requested, verify the production deployment is
|
||||
also configured correctly
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Confirm the user wants Convex Auth specifically
|
||||
- [ ] Ask whether the user wants local-only setup or production-ready setup
|
||||
- [ ] Ensure a Convex deployment is configured before running auth
|
||||
initialization
|
||||
- [ ] Install `@convex-dev/auth` and `@auth/core@0.37.0`
|
||||
- [ ] Run `npx convex dev` first if needed
|
||||
- [ ] Run `npx @convex-dev/auth`
|
||||
- [ ] Confirm `convex/auth.config.ts`, `convex/auth.ts`, and `convex/http.ts`
|
||||
were created
|
||||
- [ ] Follow the setup guide for package install and wiring
|
||||
- [ ] Add `authTables` to `convex/schema.ts`
|
||||
- [ ] Replace `ConvexProvider` with `ConvexAuthProvider`
|
||||
- [ ] Configure at least one auth method in `convex/auth.ts`
|
||||
- [ ] Run `npx convex dev --once` or the normal dev flow after setup changes
|
||||
- [ ] Confirm which sign-in methods the app needs
|
||||
- [ ] Verify the client can sign in and the backend receives authenticated
|
||||
identity
|
||||
- [ ] Offer end-to-end validation of sign up, sign out, and sign back in
|
||||
- [ ] If requested, configure the production deployment too
|
||||
- [ ] Only add extra `users` table sync if the app needs app-level user records
|
||||
Reference in New Issue
Block a user