betterauth-tanstack-convex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本指南提供了将Better Auth认证与Convex后端及TanStack Start框架集成的指导，涵盖了从安装到兼容SSR的认证流程的完整设置过程。

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

在新的Convex + TanStack Start项目中配置认证
排查Better Auth配置问题
实现注册、登录或登出流程
配置带有
```
expectAuth: true
```
的SSR认证
添加已认证的服务器函数
理解认证提供者层级

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-dev

bash

npm install convex@latest @convex-dev/better-auth
npm install better-auth@1.4.9 --save-exact
npm install @types/node --save-dev

Environment 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:3000

Convex 部署（通过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:3000

File 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

文件	用途
`convex/convex.config.ts`	注册Better Auth组件
`convex/auth.config.ts`	配置认证提供者
`convex/auth.ts`	创建Better Auth实例 + `authComponent`
`convex/http.ts`	注册认证HTTP路由
`src/lib/auth-client.ts`	客户端认证工具
`src/lib/auth-server.ts`	服务端认证工具
`src/routes/api/auth/$.ts`	将认证请求代理到Convex
`src/routes/__root.tsx`	认证提供者包装器 + SSR令牌

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'

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")

typescript

const user = await authComponent.getAuthUser(ctx)
if (!user) throw new Error("Not authenticated")

Sign Out with expectAuth

结合expectAuth的登出操作

When using

expectAuth: true

, reload the page after sign out:

typescript

await authClient.signOut({
  fetchOptions: {
    onSuccess: () => location.reload(),
  },
})

当使用

expectAuth: true

时，登出后需要重新加载页面：

typescript

await authClient.signOut({
  fetchOptions: {
    onSuccess: () => location.reload(),
  },
})

Critical Configuration

关键配置

Vite SSR Bundle

Vite SSR 打包配置

Required in

vite.config.ts

to avoid module resolution issues:

typescript

ssr: {
  noExternal: ['@convex-dev/better-auth'],
}

在

vite.config.ts

中需要添加以下配置以避免模块解析问题：

typescript

ssr: {
  noExternal: ['@convex-dev/better-auth'],
}

ConvexQueryClient with expectAuth

结合expectAuth的ConvexQueryClient配置

Required for seamless SSR authentication:

typescript

const convexQueryClient = new ConvexQueryClient(convexUrl, {
  expectAuth: true,
})

为实现流畅的SSR认证，需要进行以下配置：

typescript

const convexQueryClient = new ConvexQueryClient(convexUrl, {
  expectAuth: true,
})

Provider Hierarchy

提供者层级

The root component must wrap children in this order:

```
ConvexBetterAuthProvider
```
(outermost)
```
QueryClientProvider
```
```
RootDocument
```
with
```
<Outlet />
```

根组件必须按以下顺序包裹子组件：

```
ConvexBetterAuthProvider
```
（最外层）
```
QueryClientProvider
```
包含
```
<Outlet />
```
的
```
RootDocument
```

Reference Files

参考文件

Load the detailed setup guide when implementing authentication:

File	Use When
`references/setup-guide.md`	Full step-by-step installation and configuration

实现认证时可查看详细的设置指南：

文件	适用场景
`references/setup-guide.md`	完整的分步安装与配置指南