betterauth-tanstack-convex_skill

This skill guides you through setting up Better Auth with Convex and TanStack Start, enabling secure SSR, routes, and sign in flows.

19

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill sstobo/convex-skills --skill betterauth-tanstack-convex

SKILL.md3.5 KB

Overview

This skill documents a step-by-step guide to integrate Better Auth with a Convex backend and the TanStack Start framework. It focuses on installation, environment configuration, SSR-compatible auth flows, and required file wiring to support sign up, sign in, and sign out. Use it to implement or troubleshoot authenticated routes and server functions with expectAuth.

How this skill works

The guide walks through installing packages, setting environment variables for both local and Convex deployments, and registering Better Auth in Convex config files. It shows client and server helper files, how to proxy auth requests, and how to wrap the app with the required provider hierarchy for SSR. It also covers critical runtime settings such as Vite SSR noExternal and using ConvexQueryClient with expectAuth for server-side rendering.

When to use it

Setting up authentication in a new Convex + TanStack Start project
Adding sign up, sign in, or sign out flows
Configuring SSR authentication with expectAuth: true
Troubleshooting Better Auth or Convex auth configuration issues
Adding authenticated Convex server functions or middleware

Best practices

Install exact Better Auth package version and latest convex packages to avoid runtime mismatches
Set BETTER_AUTH_SECRET and SITE_URL in Convex deployment env and mirror site URLs in .env.local
Add ssr.noExternal for @convex-dev/better-auth in vite.config.ts to prevent SSR module resolution errors
Use ConvexQueryClient with expectAuth: true for SSR requests that require user context
Wrap the app in ConvexBetterAuthProvider outermost, then QueryClientProvider, then your RootDocument/Outlet

Example use cases

Full project setup: install packages, set env vars, register auth component in convex/convex.config.ts
SSR-protected page: use ConvexQueryClient with expectAuth to fetch user-specific data on the server
Sign-out flow: call authClient.signOut and reload the page when using expectAuth to clear server SSR state
Server function requiring auth: call authComponent.getAuthUser(ctx) and throw when no user to protect endpoints
Proxy route: implement src/routes/api/auth/$.ts to forward auth HTTP requests to Convex

FAQ

Set BETTER_AUTH_SECRET and SITE_URL in your Convex deployment. In .env.local mirror CONVEX_DEPLOYMENT, VITE_CONVEX_URL, VITE_CONVEX_SITE_URL, and VITE_SITE_URL for local development.

How do I ensure SSR works with Better Auth?

Use ConvexQueryClient with expectAuth: true, add @convex-dev/better-auth to ssr.noExternal in vite.config.ts, and wrap the app with ConvexBetterAuthProvider at the root.

How do I protect a backend function?

Call authComponent.getAuthUser(ctx) inside the function and throw or return an error if no user is returned.