--- id: authentication title: Implement Authentication in React description: Implement sessions, sign-in, sign-out, protected routes, and server-side authorization in a TanStack Start React app. --- Implement the authentication workflow in your React app, from sessions and sign-in to protected routes and authorization. To compare libraries and hosted services, read [Choose Authentication for React Apps](./authentication-overview.md). ## Authentication Approaches You have several options for authentication in your TanStack Start application: **Hosted Solutions:** 1. **[Clerk](https://clerk.dev)** - Complete authentication platform with UI components 2. **[WorkOS](https://workos.com)** - Enterprise-focused with SSO and compliance features 3. **[Better Auth](https://www.better-auth.com/)** - Open-source TypeScript library 4. **[Auth.js](https://authjs.dev/)** - Open-source library supporting 80+ OAuth providers **DIY Implementation Benefits:** - **Full Control**: Complete customization over authentication flow - **No Vendor Lock-in**: Own your authentication logic and user data - **Custom Requirements**: Implement specific business logic or compliance needs - **Cost Control**: No per-user pricing or usage limits Authentication involves many considerations including password security, session management, rate limiting, CSRF protection, and various attack vectors. ## Core Concepts ### Authentication vs Authorization - **Authentication**: Who is this user? (Login/logout) - **Authorization**: What can this user do? (Permissions/roles) TanStack Start provides server functions, request and cookie utilities, and route protection. Session storage and authentication come from your application or a library you choose. > Protect the data/API boundary first. Any server function, server route, or other API endpoint that returns or mutates private data must authorize the request itself. `beforeLoad` is useful for route UX: it keeps users out of screens they cannot use and avoids triggering work that would fail anyway. It is not the security boundary for the data. See [Authentication Server Primitives](./authentication-server-primitives.md) for the server-side pattern. ## Essential Building Blocks ### 1. Server Functions for Authentication Server functions handle sensitive authentication logic securely on the server: ```tsx import { createServerFn } from '@tanstack/react-start' import { redirect } from '@tanstack/react-router' import { getAppSession } from '~/utils/session' // Login server function export const loginFn = createServerFn({ method: 'POST' }) .validator((data: { email: string; password: string }) => data) .handler(async ({ data }) => { // Verify credentials (replace with your auth logic) const user = await authenticateUser(data.email, data.password) if (!user) { return { error: 'Invalid credentials' } } // Create session const session = await getAppSession() session.userId = user.id await session.save() // Redirect to protected area throw redirect({ to: '/dashboard' }) }) // Logout server function export const logoutFn = createServerFn({ method: 'POST' }).handler(async () => { const session = await getAppSession() session.destroy() throw redirect({ to: '/' }) }) // Get current user export const getCurrentUserFn = createServerFn({ method: 'GET' }).handler( async () => { const session = await getAppSession() const userId = session.userId if (!userId) { return null } const user = await getUserById(userId) return user ? { id: user.id, email: user.email, role: user.role } : null }, ) ``` ### 2. Session Management Start does not provide a session API. This guide uses iron-session for encrypted cookie sessions. Start's cookie helpers connect it to server functions, server routes, and request middleware. For encrypted cookie sessions, install [iron-session](https://github.com/vvo/iron-session): ```sh pnpm add iron-session ``` This example uses iron-session 9's cookie adapter. Its Node runtime requires Node 22.13 or newer; check the library's runtime requirements for other deployment targets. ```tsx // utils/session.ts — import only from server code import { getIronSession } from 'iron-session' import { getCookie, setCookie } from '@tanstack/react-start/server' type SessionData = { userId: string oauthState: string } export function getAppSession(ttl = 7 * 24 * 60 * 60) { const password = process.env.SESSION_SECRET if (!password || password.length < 32) { throw new Error('SESSION_SECRET must be at least 32 characters') } return getIronSession( { read: getCookie, write: setCookie }, { cookieName: 'app-session', password, ttl, cookieOptions: { secure: process.env.NODE_ENV === 'production', sameSite: 'lax', httpOnly: true, path: '/', }, }, ) } ``` Read fields directly from the returned session, change them, then `await session.save()` before returning or redirecting. Missing or expired sessions have no user ID. `session.destroy()` removes the browser cookie. Keep one session object for the operation; another call to `getAppSession()` reads the incoming request again. For middleware, pass that object through request context when downstream code needs the same mutations. The `getAppSession` helper belongs to your application. Start does not cache sessions, choose expiration rules, or synchronize concurrent writes. Keep secrets and session objects in server code, and read request-specific configuration inside the active request. ### 3. Authentication Context Load the current user in your root route's `beforeLoad` so the initial server render and child routes receive the same authentication state. `useServerFn` returns a callable function, not an object with `data`, `isLoading`, or `refetch`. You can call a server function directly from `beforeLoad`. Merge this pattern into your existing root route, keeping its metadata and document shell: ```tsx // routes/__root.tsx import { createRootRoute, HeadContent, Outlet, Scripts, } from '@tanstack/react-router' import type { ReactNode } from 'react' import { getCurrentUserFn } from '../server/auth' export const Route = createRootRoute({ headers: () => ({ 'Cache-Control': 'private, no-store' }), beforeLoad: async () => ({ user: await getCurrentUserFn() }), component: Outlet, shellComponent: RootDocument, }) function RootDocument({ children }: { children: ReactNode }) { return ( {children} ) } ``` The root includes session-specific data, so its responses use `Cache-Control: private, no-store`. Keep that policy on child routes that render this data, and do not override it with public caching at your CDN. Read that state from a descendant component: ```tsx // components/AuthStatus.tsx import { Route } from '../routes/__root' export function AuthStatus() { const { user } = Route.useRouteContext() return {user ? user.email : 'Signed out'} } ``` After login or logout changes the session, call `await router.invalidate()` to reload the current user and rerun route guards. Keep private-data authorization in the server function itself, even when a route already checks the user. ### 4. Route Protection Protect routes using `beforeLoad`: ```tsx // routes/_authed.tsx - Layout route for protected pages import { createFileRoute, redirect } from '@tanstack/react-router' import { getCurrentUserFn } from '../server/auth' export const Route = createFileRoute('/_authed')({ beforeLoad: async ({ location }) => { const user = await getCurrentUserFn() if (!user) { throw redirect({ to: '/login', search: { redirect: location.href }, }) } // Pass user to child routes return { user } }, }) ``` ```tsx // routes/_authed/dashboard.tsx - Protected route import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute('/_authed/dashboard')({ component: DashboardComponent, }) function DashboardComponent() { const { user } = Route.useRouteContext() return (

Welcome, {user.email}!

{/* Dashboard content */}
) } ``` ## Implementation Patterns ### Basic Email/Password Authentication ```tsx // server/auth.ts import bcrypt from 'bcryptjs' import { createServerFn } from '@tanstack/react-start' // User registration export const registerFn = createServerFn({ method: 'POST' }) .validator((data: { email: string; password: string; name: string }) => data) .handler(async ({ data }) => { // Check if user exists const existingUser = await getUserByEmail(data.email) if (existingUser) { return { error: 'User already exists' } } // Hash password const hashedPassword = await bcrypt.hash(data.password, 12) // Create user const user = await createUser({ email: data.email, password: hashedPassword, name: data.name, }) // Create session const session = await getAppSession() session.userId = user.id await session.save() return { success: true, user: { id: user.id, email: user.email } } }) async function authenticateUser(email: string, password: string) { const user = await getUserByEmail(email) if (!user) return null const isValid = await bcrypt.compare(password, user.password) return isValid ? user : null } ``` ### Role-Based Access Control (RBAC) ```tsx // utils/auth.ts export const roles = { USER: 'user', ADMIN: 'admin', MODERATOR: 'moderator', } as const type Role = (typeof roles)[keyof typeof roles] export function hasPermission(userRole: Role, requiredRole: Role): boolean { const hierarchy = { [roles.USER]: 0, [roles.MODERATOR]: 1, [roles.ADMIN]: 2, } return hierarchy[userRole] >= hierarchy[requiredRole] } // Protected route with role check export const Route = createFileRoute('/_authed/admin/')({ beforeLoad: async ({ context }) => { if (!hasPermission(context.user.role, roles.ADMIN)) { throw redirect({ to: '/unauthorized' }) } }, }) ``` ### Social Authentication Integration ```tsx // Example with OAuth providers export const authProviders = { google: { clientId: process.env.GOOGLE_CLIENT_ID!, redirectUri: `${process.env.APP_URL}/auth/google/callback`, }, github: { clientId: process.env.GITHUB_CLIENT_ID!, redirectUri: `${process.env.APP_URL}/auth/github/callback`, }, } export const initiateOAuthFn = createServerFn({ method: 'POST' }) .validator((data: { provider: 'google' | 'github' }) => data) .handler(async ({ data }) => { const provider = authProviders[data.provider] const state = generateRandomState() // Store state in session for CSRF protection const session = await getAppSession() session.oauthState = state await session.save() // Generate OAuth URL const authUrl = generateOAuthUrl(provider, state) throw redirect({ href: authUrl }) }) ``` ### Password Reset Flow ```tsx // Password reset request export const requestPasswordResetFn = createServerFn({ method: 'POST' }) .validator((data: { email: string }) => data) .handler(async ({ data }) => { const user = await getUserByEmail(data.email) if (!user) { // Don't reveal if email exists return { success: true } } const token = generateSecureToken() const expires = new Date(Date.now() + 60 * 60 * 1000) // 1 hour await savePasswordResetToken(user.id, token, expires) await sendPasswordResetEmail(user.email, token) return { success: true } }) // Password reset confirmation export const resetPasswordFn = createServerFn({ method: 'POST' }) .validator((data: { token: string; newPassword: string }) => data) .handler(async ({ data }) => { const resetToken = await getPasswordResetToken(data.token) if (!resetToken || resetToken.expires < new Date()) { return { error: 'Invalid or expired token' } } const hashedPassword = await bcrypt.hash(data.newPassword, 12) await updateUserPassword(resetToken.userId, hashedPassword) await deletePasswordResetToken(data.token) return { success: true } }) ``` ## Security Best Practices ### 1. Password Security ```tsx // Use strong hashing (bcrypt, scrypt, or argon2) import bcrypt from 'bcryptjs' const saltRounds = 12 // Adjust based on your security needs const hashedPassword = await bcrypt.hash(password, saltRounds) ``` ### 2. Session Security Set the library's server-validated expiration as well as appropriate cookie attributes. In the iron-session example, `ttl` limits a sealed credential's lifetime from its latest save; saving again renews it. A numeric `cookieOptions.maxAge` controls browser retention. In iron-session 9, explicitly setting `maxAge: undefined` also disables seal expiry; omit the property to use the configured `ttl`. Use an application-validated timestamp or a server-side record if you also need an absolute lifetime that writes cannot extend. Use `httpOnly`, `sameSite`, and `path` deliberately, and require `secure: true` on HTTPS deployments. These cookie attributes complement server-side authorization and CSRF protections. Keep only the minimum session data and load current account permissions from their authoritative store. Logout removes a stateless cookie from the current browser; it cannot revoke a copy without server-side state. ### 3. Rate Limiting ```tsx // Simple in-memory rate limiting (use Redis in production) const loginAttempts = new Map() export const rateLimitLogin = (ip: string): boolean => { const now = Date.now() const attempts = loginAttempts.get(ip) if (!attempts || now > attempts.resetTime) { loginAttempts.set(ip, { count: 1, resetTime: now + 15 * 60 * 1000 }) // 15 min return true } if (attempts.count >= 5) { return false // Too many attempts } attempts.count++ return true } ``` ### 4. Input Validation ```tsx import { z } from 'zod' const loginSchema = z.object({ email: z.string().email().max(255), password: z.string().min(8).max(100), }) export const loginFn = createServerFn({ method: 'POST' }) .validator((data) => loginSchema.parse(data)) .handler(async ({ data }) => { // data is now validated }) ``` ## Testing Authentication ### Unit Testing Server Functions ```tsx // __tests__/auth.test.ts import { describe, it, expect, beforeEach } from 'vitest' import { loginFn } from '../server/auth' describe('Authentication', () => { beforeEach(async () => { await setupTestDatabase() }) it('should login with valid credentials', async () => { const result = await loginFn({ data: { email: 'test@example.com', password: 'password123' }, }) expect(result.error).toBeUndefined() expect(result.user).toBeDefined() }) it('should reject invalid credentials', async () => { const result = await loginFn({ data: { email: 'test@example.com', password: 'wrongpassword' }, }) expect(result.error).toBe('Invalid credentials') }) }) ``` ### Integration Testing ```tsx // __tests__/auth-flow.test.tsx import { render, screen, fireEvent, waitFor } from '@testing-library/react' import { RouterProvider, createMemoryHistory } from '@tanstack/react-router' import { router } from '../router' describe('Authentication Flow', () => { it('should redirect to login when accessing protected route', async () => { const history = createMemoryHistory() history.push('/dashboard') // Protected route render() await waitFor(() => { expect(screen.getByText('Login')).toBeInTheDocument() }) }) }) ``` ## Common Patterns ### Loading States Call the function returned by `useServerFn` with `{ data }`. Track pending state in the component, handle invalid credentials, and refresh route context after a successful login. This form uses the `loginFn` from the server-functions example above. It requires JavaScript, so the fields stay disabled until hydration; `method="post"` also prevents credentials appearing in a native GET submission. ```tsx // components/LoginForm.tsx import { useState } from 'react' import type { FormEvent } from 'react' import { useHydrated, useRouter } from '@tanstack/react-router' import { useServerFn } from '@tanstack/react-start' import { loginFn } from '../server/auth' export function LoginForm() { const hydrated = useHydrated() const [isLoading, setIsLoading] = useState(false) const [error, setError] = useState('') const login = useServerFn(loginFn) const router = useRouter() const handleSubmit = async (event: FormEvent) => { event.preventDefault() const formData = new FormData(event.currentTarget) const email = formData.get('email') const password = formData.get('password') if (typeof email !== 'string' || typeof password !== 'string') { return } setIsLoading(true) setError('') try { const result = await login({ data: { email, password } }) if (result?.error) { setError(result.error) return } await router.invalidate() } catch { setError('Login failed. Please try again.') } finally { setIsLoading(false) } } return (

{error}

) } ``` ### Remember Me Functionality ```tsx export const loginFn = createServerFn({ method: 'POST' }) .validator( (data: { email: string; password: string; rememberMe?: boolean }) => data, ) .handler(async ({ data }) => { const user = await authenticateUser(data.email, data.password) if (!user) { return { error: 'Invalid credentials' } } const ttl = data.rememberMe ? 30 * 24 * 60 * 60 : 8 * 60 * 60 const session = await getAppSession(ttl) session.userId = user.id await session.save() return { success: true } }) ``` ## Working Examples Study these implementations to understand different authentication patterns: - **[Basic Auth with Prisma](https://github.com/TanStack/router/tree/main/examples/react/start-basic-auth)** - Complete DIY implementation with database and sessions - **[Supabase Integration](https://github.com/TanStack/router/tree/main/examples/react/start-supabase-basic)** - Third-party service integration example - **[Client-side Context Auth](https://github.com/TanStack/router/tree/main/examples/react/authenticated-routes)** - Client-only authentication patterns ## Migration from Other Solutions ### From Client-Side Auth If you're migrating from client-side authentication (localStorage, context only): 1. Move authentication logic to server functions 2. Replace localStorage with server sessions 3. Update route protection to use `beforeLoad` 4. Add proper security headers and CSRF protection ### From Other Frameworks - **Next.js**: Replace API routes with server functions, migrate NextAuth sessions - **SvelteKit**: Move form actions to server functions, update route protection ## Production Considerations When choosing your authentication approach, consider these factors: ### Hosted vs DIY Comparison **Hosted Solutions (Clerk, WorkOS, Better Auth):** - Pre-built security measures and regular updates - UI components and user management features - Compliance certifications and audit trails - Support and documentation - Per-user or subscription pricing **DIY Implementation:** - Complete control over implementation and data - No ongoing subscription costs - Custom business logic and workflows - Responsibility for security updates and monitoring - Need to handle edge cases and attack vectors ### Security Considerations Authentication systems need to handle various security aspects: - Password hashing and timing attack prevention - Session management and fixation protection - CSRF and XSS protection - Rate limiting and brute force prevention - OAuth flow security - Compliance requirements (GDPR, CCPA, etc.) ## Next Steps When implementing authentication, consider: - **Security Review**: Review your implementation for security best practices - **Performance**: Add caching for user lookups and session validation - **Monitoring**: Add logging and monitoring for authentication events - **Compliance**: Ensure compliance with relevant regulations if storing personal data For other authentication approaches, check the [Authentication Overview](./authentication-overview.md). For specific integration help, explore our [working examples](https://github.com/TanStack/router/tree/main/examples/react).