Implement Authentication in React

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 Approaches

You have several options for authentication in your TanStack Start application:

Hosted Solutions:

Clerk - Complete authentication platform with UI components
WorkOS - Enterprise-focused with SSO and compliance features
Better Auth - Open-source TypeScript library
Auth.js - 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 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:

shell

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<SessionData>(
    { 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 (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}

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 <span>{user ? user.email : 'Signed out'}</span>
}

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 (
    <div>
      <h1>Welcome, {user.email}!</h1>
      {/* Dashboard content */}
    </div>
  )
}

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' })
    }
  },
})

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<string, { count: number; resetTime: number }>()

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(<RouterProvider router={router} history={history} />)

    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<HTMLFormElement>) => {
    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 (
    <form method="post" onSubmit={handleSubmit}>
      <fieldset disabled={!hydrated || isLoading}>
        <label>
          Email
          <input name="email" type="email" autoComplete="username" required />
        </label>
        <label>
          Password
          <input
            name="password"
            type="password"
            autoComplete="current-password"
            required
          />
        </label>
        <button type="submit" disabled={isLoading}>
          {isLoading ? 'Logging in...' : 'Login'}
        </button>
      </fieldset>
      <p role="alert">{error}</p>
    </form>
  )
}

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 - Complete DIY implementation with database and sessions
Supabase Integration - Third-party service integration example
Client-side Context Auth - Client-only authentication patterns

Migration from Other Solutions

From Client-Side Auth

If you're migrating from client-side authentication (localStorage, context only):

Move authentication logic to server functions
Replace localStorage with server sessions
Update route protection to use beforeLoad
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. For specific integration help, explore our working examples.