WorkOS Docs Homepage
SDKs
API referenceDashboardSign In
SDKs

AuthKit TanStack Start SDK

github.com
workos/authkit-tanstack-start
26 Stars
6 Forks
4 Contributors
github.com
Official AuthKit SDK for TanStack Start applications.

Installation

Usage

The AuthKit TanStack Start SDK provides utilities for integrating AuthKit authentication into TanStack Start applications.

Refer to the AuthKit documentation for detailed usage instructions and examples.

Beta Versions

Certain WorkOS features may be available only in the beta version of the SDK. Beta versions have the -beta.* suffix, for example, 3.2.0-beta.1. For more information on how to use the beta versions, refer to the README in the GitHub repository.

Releases

January 16, 2026

v0.5.0

Latest
January 16, 2026

What's Changed

  • docs(readme): clarify sign-out redirect configuration by @sundaray in #42
  • feat: add redirectUri option to middleware by @nicknisi in #29
  • v0.5.0 by @nicknisi in #47

New Contributors

  • @sundaray made their first contribution in #42

Full Changelog: v0.4.1...v0.5.0

December 18, 2025

v0.4.1

December 18, 2025

What's Changed

  • Add context7.json to repo by @nicknisi in #35
  • fix types in tests by @nicknisi in #34
  • feat: use npm Trusted Publishers for releases by @nicknisi in #37
  • feat: pass all options through getSignInUrl and getSignUpUrl by @nicknisi in #36
  • fix: use Node 24 for npm 11+ (required by Trusted Publishers) by @nicknisi in #39

Full Changelog: v0.3.1...v0.4.1

December 16, 2025

v0.3.1

December 16, 2025

What's Changed

  • fix: prevent CORS errors when calling signOut from useAuth hook by @nicknisi in #31
  • v0.3.1 by @nicknisi in #32

Full Changelog: v0.3.0...v0.3.1

December 16, 2025

v0.3.0

December 16, 2025

What's Changed

  • change node version in release version by @nicknisi in #15
  • fix: correct handleCallbackRoute usage in README examples by @nicknisi in #16
  • fix: improve URL validation in signOut redirect logic by @rgcottrell in #21
  • Fix client bundling and upgrade authkit-session to 0.3.0 by @nicknisi in #26
  • Export authkit instance for middleware configuration by @juliusmarminge in #14
  • feat: allow passing initial state to provider by @juliusmarminge in #17
  • Update package dependencies by @nicknisi in #28
  • fix: remove unused ensureSignedIn parameter from server actions by @nicknisi in #27
  • Release v0.3.0 by @nicknisi in #30

New Contributors

  • @rgcottrell made their first contribution in #21
  • @juliusmarminge made their first contribution in #14

Full Changelog: v0.2.0...v0.3.0

October 27, 2025

v0.2.0

October 27, 2025

What's Changed

  • chore: remove dotenv from example vite.config by @nicknisi in #10
  • feat: add onSuccess and onError hooks to callback route by @nicknisi in #9
  • Fix signOut to delete the configured session cookie name by @nicknisi in #8
  • Package updates and type fixes by @nicknisi in #12

Full Changelog: v0.1.0...v0.2.0

October 6, 2025

v0.1.0

October 6, 2025

Release Notes: v0.1.0

Release Date: October 6, 2025

This is the initial release of @workos/authkit-tanstack-react-start, bringing WorkOS AuthKit authentication to TanStack Start applications.

🎉 What's New

This release provides a complete authentication solution for TanStack Start, built on top of the battle-tested @workos/authkit-session library. It includes both server-side and client-side APIs designed specifically for TanStack Start's architecture.

Server-Side Features

Authentication Functions

  • getAuth() - Get the current authenticated user in loaders and server functions
  • getSignInUrl() / getSignUpUrl() - Generate AuthKit URLs with automatic state management
  • getAuthorizationUrl() - Full control over OAuth parameters (screen hints, organization, etc.)
  • signOut() - Sign out the current user and revoke their session
  • switchToOrganization() - Switch user context to a different organization

Route Handlers

  • handleCallbackRoute - Complete OAuth callback handler for /api/auth/callback
  • authkitMiddleware() - Request middleware for session management

Client-Side Features

React Hooks

  • useAuth() - Access user info and loading state in client components
  • useAccessToken() - Get the current access token with automatic refresh
  • useTokenClaims() - Access JWT claims from the current session

Components

  • AuthKitProvider - Context provider for client-side hooks (only needed if using client hooks)

Session Management

  • Cookie-based sessions using iron-session encryption
  • Automatic token refresh when tokens are expiring
  • JWKS-based token verification
  • Support for impersonation workflows
  • Organization switching
  • Configurable cookie settings (domain, maxAge, sameSite, etc.)

🎯 Design Philosophy

This SDK is designed with TanStack Start's architecture in mind:

  1. Server-First: Primary API uses TanStack Start server functions (createServerFn)
  2. Type-Safe: Full TypeScript support with comprehensive type definitions
  3. Zero-Config: Works with environment variables, no manual configuration needed
  4. Flexible: Use server-side only, or add client hooks when needed
  5. Framework-Aligned: Follows TanStack Start patterns (loaders, middleware, server functions)

🚨 Important Notes

TanStack Start Compatibility

This library is designed for TanStack Start v1.0+. TanStack Start is currently in RC/beta, so expect some API changes as the framework stabilizes. We've designed the SDK to be flexible enough to adapt to framework changes.

Server Function Execution Context

Server functions created with createServerFn can ONLY be called from:

  • Route loader functions ✅
  • Other server functions ✅
  • Route server handlers ✅

NOT from:

  • Route beforeLoad functions ❌ (runs on both server and client)
  • Client components directly ❌ (use hooks instead)

See the README for detailed execution context information.

File Organization Matters

The SDK follows TanStack Start's bundler conventions:

  • Server code lives in src/server/
  • Client code lives in src/client/
  • The bundler uses these paths to determine what code to include in which bundles

📚 Documentation

Complete documentation is available in the README.md, including:

  • Quick start guide
  • Environment variable configuration
  • Usage examples for all APIs
  • Integration patterns
  • Troubleshooting guide

🔗 Resources

  • GitHub Repository: https://github.com/workos/authkit-tanstack-start
  • npm Package: https://www.npmjs.com/package/@workos/authkit-tanstack-react-start
  • WorkOS Documentation: https://workos.com/docs/user-management
  • TanStack Start Docs: https://tanstack.com/start/latest

🙏 Acknowledgments

This SDK is inspired by and follows patterns from:

  • @workos-inc/authkit-nextjs - The reference implementation for Next.js
  • @workos/authkit-session - The core session management library
  • The TanStack Start example implementation that proved the concept

🐛 Known Issues

  • None at this time. Please report issues at https://github.com/workos/authkit-tanstack-start/issues

Install now:

npm install @workos/authkit-tanstack-react-start

pnpm add @workos/authkit-tanstack-react-start

Get started in 3 steps - see the README for the quickstart guide.