Fix client bundling and upgrade authkit-session to 0.3.0

[nicknisi]

Summary

This PR upgrades @workos/authkit-session to 0.3.0 and fixes critical session persistence issues.

Problem: Can't Use TanStack's Built-in setResponseHeaders

TanStack Start provides setResponseHeaders() for setting cookies from server functions. However, importing it breaks builds:

"Readable" is not exported by "__vite-browser-external"

This happens because TanStack's barrel exports pull in node:stream code that Vite can't handle. This is a known issue (TanStack/router#4022).

Impact: When refreshSession() or switchToOrganization() is called, the session cookie can't be persisted. Users switch orgs successfully, but on page refresh they revert to their previous org.

Solution: Context-Based Session Persistence

Instead of importing from @tanstack/react-start/server, we use middleware context to defer cookie persistence:

1. Middleware creates context with `__setPendingHeader` setter
2. Server function refreshes session → gets encryptedSession
3. Server function stores pending header via context setter
4. Middleware reads pending headers after args.next() completes
5. Middleware applies cookies to the response

This follows the standard middleware pattern used in Express/Koa/etc.

Additional Fixes

• Client bundling (@workos-inc/node is being loaded in browser causing "pluralize module not found" error with Convex integration #18): Dynamic imports prevent server deps from leaking into client bundles
• AsyncLocalStorage context error: getAuthKitContextOrNull() now gracefully handles unavailable context (e.g., after middleware completes)
• Logout redirect CORS: Example app logout links use reloadDocument to avoid CORS issues with external redirects

Changes

• storage.ts - No TanStack server imports; uses context for headers
• middleware.ts - Passes header setter through context, applies pending headers to response
• auth-helpers.ts - Returns session data for middleware to persist
• context.ts - Try-catch for graceful context access
• server-functions.ts / actions.ts - Use context-based persistence

Related

• Fixes session refresh propagation
• Fixes @workos-inc/node is being loaded in browser causing "pluralize module not found" error with Convex integration #18 (client bundling)
• Works around Readable is not exported by __vite-browser-external TanStack/router#4022 (setResponseHeaders bundling)

[greptile-apps]

Greptile Overview

Greptile Summary

This PR upgrades @workos/authkit-session to 0.3.0 and implements a comprehensive solution for session persistence and client bundling issues.

Key Changes:

• Replaced static authkit import with lazy-loaded getAuthkit() to prevent server-only dependencies (@workos-inc/node, pluralize) from being bundled into client code, fixing issue @workos-inc/node is being loaded in browser causing "pluralize module not found" error with Convex integration #18
• Implemented context-based header persistence pattern via middleware to work around TanStack's setResponseHeaders bundling issue (Readable is not exported by __vite-browser-external TanStack/router#4022)
• Added new modules: context.ts for global context access, auth-helpers.ts for consolidated auth operations, authkit-loader.ts for lazy service instantiation
• Refactored actions and server-functions to use the new helper modules with proper client sanitization (stripping accessToken from client responses)
• Added reloadDocument to logout links in example app to prevent CORS issues with external redirects

Architecture:
The session persistence now flows through middleware context: server functions store pending headers via __setPendingHeader, and middleware applies them to the response after args.next() completes. This pattern ensures cookies are properly set even when TanStack's context becomes unavailable post-handler.

Testing:
Comprehensive test coverage added for all new modules including middleware header merging, context availability, auth helpers, and client-side organization switching.

Confidence Score: 5/5

• This PR is safe to merge - it fixes critical bundling and session persistence issues with a well-tested implementation
• Score reflects: comprehensive test coverage for all new functionality, no security concerns (tokens properly stripped from client responses), clean architectural pattern for header persistence, and fixes real user-reported issues (@workos-inc/node is being loaded in browser causing "pluralize module not found" error with Convex integration #18)
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
src/server/middleware.ts	5/5	Refactored to use lazy-loaded authkit and context-based header persistence. Properly handles multiple Set-Cookie headers via append, preserves existing response headers, and applies refreshed session cookies after args.next().
src/server/context.ts	5/5	New file providing context utilities for accessing middleware-set auth state. getAuthKitContextOrNull gracefully handles unavailable context with try-catch.
src/server/storage.ts	5/5	Updated to use context-based header persistence when available, with fallback to response headers when context is unavailable (e.g., after args.next() in middleware).
src/server/authkit-loader.ts	5/5	New lazy-loading orchestrator for AuthKit service. Uses singleton pattern for authkit instance. Replaces static import to prevent server deps from leaking into client bundles.
src/server/auth-helpers.ts	5/5	New helper module consolidating auth operations. Contains getRawAuthFromContext, isAuthConfigured, getSessionWithRefreshToken, refreshSession, and decodeState utilities.
src/server/actions.ts	5/5	Refactored to use auth-helpers module. Added sanitizeAuthForClient to strip accessToken before sending to client. Improved error handling with isAuthConfigured checks.
src/server/server-functions.ts	5/5	Updated to use lazy-loaded getAuthkit() and consolidated auth-helpers. signOut now uses authkit.signOut() for proper session cleanup. switchToOrganization delegates to refreshSession helper.
src/server/server.ts	5/5	Simplified OAuth callback handler using consolidated decodeState helper. extractSessionHeaders function handles both response.headers and direct headers object patterns.
src/index.ts	5/5	Simplified to re-export types and server/index.ts. Removes explicit exports in favor of barrel export pattern.
package.json	5/5	Updated @workos/authkit-session to 0.3.0 and upgraded dev dependencies including TanStack packages to 1.140.0.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Middleware
    participant ServerFunction
    participant AuthKit
    participant Storage

    Client->>Middleware: Request
    Middleware->>AuthKit: getAuthkit()
    AuthKit-->>Middleware: authkit instance
    Middleware->>AuthKit: withAuth(request)
    AuthKit-->>Middleware: { auth, refreshedSessionData }
    
    Note over Middleware: Create pendingHeaders & context with __setPendingHeader
    
    Middleware->>ServerFunction: args.next({ context })
    
    alt Server function refreshes session
        ServerFunction->>AuthKit: refreshSession(orgId)
        AuthKit->>Storage: saveSession()
        Storage->>Storage: getAuthKitContextOrNull()
        alt Context available
            Storage->>Middleware: __setPendingHeader(Set-Cookie, value)
        else Context unavailable
            Storage-->>ServerFunction: { response with headers }
        end
    end
    
    ServerFunction-->>Middleware: result
    
    alt refreshedSessionData exists
        Middleware->>AuthKit: saveSession(undefined, refreshedSessionData)
        AuthKit-->>Middleware: { response with Set-Cookie }
        Middleware->>Middleware: Extract & append Set-Cookie to pendingHeaders
    end
    
    Middleware->>Middleware: Apply pendingHeaders to response
    Middleware-->>Client: Response with session cookies

Loading

[greptile-apps]

_{18 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[briggsrrr]

🙏

[nicknisi]

@greptileai

[greptile-apps]

_{28 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}