How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/sstobo/convex-skills --skill betterauth-tanstack-convexBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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 |
