better auth/integrations

13 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

TanStack Start integration CLI setup

To create a new TanStack Start project with Better Auth integrated, run `npm create @tanstack/start` and select Better Auth from the add-ons prompt. The CLI sets up a project with an auth instance configured with the plugin and mounted handlers.

Mount Better Auth handler in TanStack Start

Create a file at `/src/routes/api/auth/$.ts` that exports a Route with server handlers. Both GET and POST handlers should call `await auth.handler(request)` and accept a request object of type Request.

Use client SDK over server actions in TanStack Start

When using Better Auth with TanStack Start, the recommended approach is to use the client SDK or authClient to handle authentication rather than calling auth.api directly with server actions.

Create server function for getSession in TanStack Start

Create a server function using `createServerFn({ method: 'GET' })` that calls `auth.api.getSession({ headers })` where headers are obtained from `getRequestHeaders()`. This function can be used to check the session on both routes and server functions.

Create server function for ensureSession in TanStack Start

Create a server function using `createServerFn({ method: 'GET' })` that calls `auth.api.getSession({ headers })` and throws an error with message 'Unauthorized' if the session is null. This function is useful for protecting server functions.

Protect individual routes in TanStack Start

Use `beforeLoad` in route definitions to protect routes. Call `getSession()` in beforeLoad, and if session is null, throw `redirect({ to: '/login' })`. Return the session data to make it available via `Route.useRouteContext()`.

Protect multiple routes with layout in TanStack Start

Create a pathless layout route (e.g., `_protected.tsx`) with `beforeLoad` that checks authentication. If session is null, throw `redirect({ to: '/login', search: { redirect: location.href } })` to preserve the original location. Nest protected routes under this layout route.

Protect server functions in TanStack Start

Use the `ensureSession` helper in server functions created with `createServerFn`. Call `ensureSession()` in the handler to ensure the user is authenticated, which will throw an 'Unauthorized' error if there is no session.

beforeLoad ensures auth check on all navigation in TanStack Start

Using `beforeLoad` with session checking ensures authentication is validated on every navigation, including client-side navigation via Link components, not just full page loads.

Cognito setup prerequisites

To integrate with Cognito, you need to set up a User Pool and an App client in the Amazon Cognito Console. The User Pool is required for Cognito authentication.

Cognito app client configuration steps

In the Cognito Console, create a User Pool, then create an App client under App clients and note the Client ID and Client Secret if enabled. Go to Domain and set a Cognito Hosted UI domain (e.g., your-app.auth.us-east-1.amazoncognito.com). In App client settings, enable Authorization code grant OAuth flow and openid, profile, email OAuth scopes. Add your callback URL (e.g., http://localhost:3000/api/auth/callback/cognito). The callback URL must match exactly what you configure in Cognito.

Cognito configuration code example

import { betterAuth } from "better-auth"; export const auth = betterAuth({ socialProviders: { cognito: { clientId: process.env.COGNITO_CLIENT_ID as string, clientSecret: process.env.COGNITO_CLIENT_SECRET as string, domain: process.env.COGNITO_DOMAIN as string, region: process.env.COGNITO_REGION as string, userPoolId: process.env.COGNITO_USERPOOL_ID as string, }, }, })

Cognito token storage with storeAccountCookie

In database-less setups, Better Auth stores provider account data including OAuth token material in the encrypted account_data cookie when storeAccountCookie is enabled. Token refresh responses set an updated cookie, so server-side callers must forward the returned Set-Cookie header to the browser. Cognito JWTs can be large; Better Auth chunks oversized account cookies, but browsers and proxies can still enforce total header limits. Use database-backed account storage for large token payloads or production flows that need durable token storage.

Give your agent this brain