사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/sstobo/convex-skills --skill betterauth-tanstack-convex시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
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 |
