Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/sstobo/convex-skills --skill betterauth-tanstack-convexAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
Better Auth + Convex + TanStack Start
Overview
This skill provides guidance for integrating Better Auth authentication with Convex backend and TanStack Start framework. It covers the complete setup process from installation to SSR-compatible authentication flows.
When to Use This Skill
- Setting up authentication in a new Convex + TanStack Start project
- Troubleshooting Better Auth configuration issues
- Implementing sign up, sign in, or sign out flows
- Configuring SSR authentication with
expectAuth: true - Adding authenticated server functions
- Understanding the auth provider hierarchy
Quick Reference
Required Packages
bash
npm install convex@latest @convex-dev/better-auth
npm install better-auth@1.4.9 --save-exact
npm install @types/node --save-devEnvironment Variables
Convex deployment (via CLI):
bash
npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
npx convex env set SITE_URL http://localhost:3000.env.local:
bash
CONVEX_DEPLOYMENT=dev:adjective-animal-123
VITE_CONVEX_URL=https://adjective-animal-123.convex.cloud
VITE_CONVEX_SITE_URL=https://adjective-animal-123.convex.site
VITE_SITE_URL=http://localhost:3000File Structure
| File | Purpose |
|---|---|
convex/convex.config.ts | Register Better Auth component |
convex/auth.config.ts | Configure auth provider |
convex/auth.ts | Create Better Auth instance + authComponent |
convex/http.ts | Register auth HTTP routes |
src/lib/auth-client.ts | Client-side auth utilities |
src/lib/auth-server.ts | Server-side auth utilities |
src/routes/api/auth/$.ts | Proxy auth requests to Convex |
src/routes/__root.tsx | Auth provider wrapper + SSR token |
Essential Imports
typescript
// Client-side
import { authClient } from '~/lib/auth-client'
// Server-side
import { getToken, fetchAuthQuery, fetchAuthMutation } from '~/lib/auth-server'
// Backend
import { authComponent, createAuth } from './auth'Auth Check (Backend)
typescript
const user = await authComponent.getAuthUser(ctx)
if (!user) throw new Error("Not authenticated")Sign Out with expectAuth
When using expectAuth: true, reload the page after sign out:
typescript
await authClient.signOut({
fetchOptions: {
onSuccess: () => location.reload(),
},
})Critical Configuration
Vite SSR Bundle
Required in vite.config.ts to avoid module resolution issues:
typescript
ssr: {
noExternal: ['@convex-dev/better-auth'],
}ConvexQueryClient with expectAuth
Required for seamless SSR authentication:
typescript
const convexQueryClient = new ConvexQueryClient(convexUrl, {
expectAuth: true,
})Provider Hierarchy
The root component must wrap children in this order:
ConvexBetterAuthProvider(outermost)QueryClientProviderRootDocumentwith<Outlet />
Reference Files
Load the detailed setup guide when implementing authentication:
| File | Use When |
|---|---|
references/setup-guide.md | Full step-by-step installation and configuration |
