Skip to content

Releases: workos/authkit-tanstack-start

v0.1.0

06 Oct 15:53
@nicknisi nicknisi
v0.1.0
0f3eb43
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v0.1.0 Latest
Latest

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

🙏 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

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.

Assets 2
Loading