Skip to content
Source
Sign inSign up
TanStack/router

examples: Update WorkOS example to use new AuthKit SDK #5394

Mergednicknisi(GitHub profile, opens in a new tab)merged 11 commits intomain fromrefs/pull/5394/headmerged by schiller-manuel(GitHub profile, opens in a new tab)

This PR updates the start-workos example to use the new @workos/authkit-tanstack-react-start SDK instead of the custom implementation.

What changed

  • Replaced custom AuthKit implementation with the official SDK package
  • Removed all the manual session management, cookie handling, and JWKS verification code
  • Updated routes to use the SDK's built-in getAuth() and getSignInUrl() server functions
  • Added AuthKitProvider for client-side auth state management

Why

We built an official SDK that handles all the AuthKit integration details, so this example should demonstrate the recommended approach rather than a custom implementation. Makes the example cleaner and easier to follow.

Summary by CodeRabbit

  • New Features

    • Added a Client Demo page showing client-side auth hooks, tokens, org switching, and sign-out methods; linked in navigation.
    • Integrated an AuthKit provider so loaders use new auth APIs for user and sign-in URLs.
  • Refactor

    • Replaced local SSR auth implementation with the external AuthKit integration.
  • Chores

    • Added AuthKit dependency, Radix theme CSS, Vite SSR tweak, and CSS URL TypeScript declarations.
    1. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-server-core

    2. Walkthrough

      The PR removes the repository's custom server-side AuthKit SSR implementation and replaces it with the official @workos/authkit-tanstack-react-start integration: deleted internal auth SSR modules, added middleware via a new startInstance, updated routes/loaders to call library APIs, added a client demo route, CSS and Vite/type adjustments.

      Changes

      Cohort / File(s)Summary
      Package & Build
      examples/react/start-workos/package.json, examples/react/start-workos/vite.config.ts
      Added @workos/authkit-tanstack-react-start dependency and reordered postcss; added ssr.noExternal: ['@radix-ui/themes'] to Vite config.
      Removed Custom Auth SSR Layer
      Deleted files: examples/react/start-workos/src/authkit/serverFunctions.ts, examples/react/start-workos/src/authkit/ssr/config.ts, examples/react/start-workos/src/authkit/ssr/interfaces.ts, examples/react/start-workos/src/authkit/ssr/session.ts, examples/react/start-workos/src/authkit/ssr/utils.ts, examples/react/start-workos/src/authkit/ssr/workos.ts
      Removed all custom server functions, configuration management, TypeScript interfaces, session handling (cookie encryption/decryption, JWKS/token verification/refresh), lazy utilities, and WorkOS instance initialization.
      Start / Middleware
      examples/react/start-workos/src/start.ts
      Added startInstance exporting a TanStack Start instance configured with authkitMiddleware() in requestMiddleware.
      Routes — Auth Integration
      examples/react/start-workos/src/routes/__root.tsx, .../src/routes/index.tsx, .../src/routes/_authenticated.tsx, .../src/routes/_authenticated/account.tsx, .../src/routes/logout.tsx, .../src/routes/api/auth/callback.tsx
      Replaced local auth implementations with @workos/authkit-tanstack-react-start APIs (e.g., getAuth, getSignInUrl, signOut, handleCallbackRoute); converted several beforeLoad usages to loader and updated data shapes.
      New Client Demo Route & Route Types
      examples/react/start-workos/src/routes/client.tsx, examples/react/start-workos/src/routeTree.gen.ts
      Added /client file route and UI demonstrating client-side hooks (useAuth, useAccessToken); injected ClientRoute into generated route maps/types and updated start/type wiring to include startInstance.getOptions.
      Styling & Types
      examples/react/start-workos/src/app.css, examples/react/start-workos/src/vite-env.d.ts
      Added Radix UI theme import in app.css; added Vite CSS URL module declaration and /// <reference types="vite/client" /> in vite-env.d.ts.
      Route generation updates
      examples/react/start-workos/src/routeTree.gen.ts
      Updated generated router/type declarations: added /client to unions, and extended @tanstack/react-start Register config type to use startInstance.getOptions.

      Sequence Diagram(s)

      sequenceDiagram
          actor User
          participant Browser
          participant Server
          participant AuthKitLib as AuthKit Lib (middleware)
          participant WorkOS
      
          rect #F0F8FF
          Note over Server,AuthKitLib: New flow — authkitMiddleware attached to Start
          end
      
          User->>Browser: Navigate
          Browser->>Server: HTTP request
          Server->>AuthKitLib: middleware runs (auth context)
          AuthKitLib-->>Server: attach auth context
      
          rect #E8FFF0
          Note over Server: Loader invokes getAuth()/getSignInUrl()
          end
      
          Server->>AuthKitLib: getAuth()
          AuthKitLib-->>Server: returns user/tokens
          alt unauthenticated
              Server->>AuthKitLib: getSignInUrl()
              AuthKitLib->>WorkOS: request auth URL
              WorkOS-->>AuthKitLib: authorization URL
              AuthKitLib-->>Server: sign-in URL
              Server-->>Browser: redirect to sign-in
          else authenticated
              Server-->>Browser: render protected content
          end
      
          rect #FFF8E8
          Note over Browser: Client demo (/client) uses useAuth()/useAccessToken() hooks
          end
      
          Browser->>Browser: hooks call refresh/signOut/switch-org (client-side)

      Estimated code review effort

      🎯 4 (Complex) | ⏱️ ~50 minutes

      • TanStack/router#5514 — Similar migration replacing local SSR auth wiring with the external auth SDK and adding Start middleware.
      • TanStack/router#5048 — Overlaps on routeTree and auth callback routing changes.

      Suggested reviewers

      • SeanCassiere
      • schiller-manuel

      Poem

      🐰 "I hopped through code both near and far,

      Old server burrows cleared for a shiny star. Middleware sprouted, hooks now play, A client demo hops to show the way. Carrots for tests — let the auth run sway!"

      Pre-merge checks and finishing touches

      ❌ Failed checks (1 warning)
      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.You can run @coderabbitai generate docstrings to improve docstring coverage.
      ✅ Passed checks (2 passed)
      Check nameStatusExplanation
      Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
      Title Check✅ PassedThe PR title "examples: Update WorkOS example to use new AuthKit SDK" directly and clearly reflects the primary objective of the changeset. The main change across all modified files is the migration from a custom AuthKit implementation to the official @workos/authkit-tanstack-react-start SDK. The title accurately identifies which example is being updated (the WorkOS example) and the nature of the change (adopting the new AuthKit SDK), which aligns with the substantial refactoring shown in the file summaries—removing internal authentication modules and replacing them with imports from the new SDK package.
      ✨ Finishing touches
      • 📝 Generate docstrings
        🧪 Generate unit tests (beta)
      • Create PR with unit tests
      • Post copyable unit tests in a comment

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    3. View your CI Pipeline Execution ↗ for commit 136b1c338eb2ec4aafd8ead80ebf020fad90b991

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded14m 11sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded22sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-02-05 21:25:18 UTC

    4. More templates

      @tanstack/arktype-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5394

      @tanstack/eslint-plugin-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5394

      @tanstack/history

      npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5394

      @tanstack/nitro-v2-vite-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@5394

      @tanstack/react-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5394

      @tanstack/react-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5394

      @tanstack/react-router-ssr-query

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5394

      @tanstack/react-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5394

      @tanstack/react-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5394

      @tanstack/react-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5394

      @tanstack/router-cli

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5394

      @tanstack/router-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5394

      @tanstack/router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5394

      @tanstack/router-devtools-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5394

      @tanstack/router-generator

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5394

      @tanstack/router-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5394

      @tanstack/router-ssr-query-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5394

      @tanstack/router-utils

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5394

      @tanstack/router-vite-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5394

      @tanstack/solid-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5394

      @tanstack/solid-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5394

      @tanstack/solid-router-ssr-query

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@5394

      @tanstack/solid-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5394

      @tanstack/solid-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5394

      @tanstack/solid-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5394

      @tanstack/start-client-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5394

      @tanstack/start-fn-stubs

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@5394

      @tanstack/start-plugin-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5394

      @tanstack/start-server-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5394

      @tanstack/start-static-server-functions

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@5394

      @tanstack/start-storage-context

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5394

      @tanstack/valibot-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5394

      @tanstack/virtual-file-routes

      npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5394

      @tanstack/vue-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router@5394

      @tanstack/vue-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-devtools@5394

      @tanstack/vue-router-ssr-query

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-ssr-query@5394

      @tanstack/vue-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@5394

      @tanstack/vue-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@5394

      @tanstack/vue-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@5394

      @tanstack/zod-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5394

      commit: 136b1c3

    5. Actionable comments posted: 1

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between a5fdf290cb9be6a640a0dc85d29c75fd83081f11 and 4a0989764b2e455e90bbe36239f878279e033e2d.

      ⛔ Files ignored due to path filters (1)
      • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
      📒 Files selected for processing (20)
      • examples/react/start-workos/package.json (2 hunks)
      • examples/react/start-workos/src/app.css (1 hunks)
      • examples/react/start-workos/src/authkit/serverFunctions.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/config.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/interfaces.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/session.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/utils.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/workos.ts (0 hunks)
      • examples/react/start-workos/src/routeTree.gen.ts (8 hunks)
      • examples/react/start-workos/src/routes/__root.tsx (3 hunks)
      • examples/react/start-workos/src/routes/_authenticated.tsx (1 hunks)
      • examples/react/start-workos/src/routes/_authenticated/account.tsx (1 hunks)
      • examples/react/start-workos/src/routes/api/auth/callback.tsx (1 hunks)
      • examples/react/start-workos/src/routes/client.tsx (1 hunks)
      • examples/react/start-workos/src/routes/index.tsx (2 hunks)
      • examples/react/start-workos/src/routes/logout.tsx (1 hunks)
      • examples/react/start-workos/src/start.ts (1 hunks)
      • examples/react/start-workos/src/vite-env.d.ts (1 hunks)
      • examples/react/start-workos/vite.config.ts (2 hunks)
      • packages/start-server-core/package.json (1 hunks)
      💤 Files with no reviewable changes (6)
      • examples/react/start-workos/src/authkit/ssr/utils.ts
      • examples/react/start-workos/src/authkit/ssr/session.ts
      • examples/react/start-workos/src/authkit/ssr/interfaces.ts
      • examples/react/start-workos/src/authkit/serverFunctions.ts
      • examples/react/start-workos/src/authkit/ssr/workos.ts
      • examples/react/start-workos/src/authkit/ssr/config.ts
      🧰 Additional context used
      📓 Path-based instructions (5)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • examples/react/start-workos/src/vite-env.d.ts
      • examples/react/start-workos/src/routes/index.tsx
      • examples/react/start-workos/src/routes/api/auth/callback.tsx
      • examples/react/start-workos/src/start.ts
      • examples/react/start-workos/src/routes/logout.tsx
      • examples/react/start-workos/src/routes/_authenticated/account.tsx
      • examples/react/start-workos/src/routeTree.gen.ts
      • examples/react/start-workos/src/routes/client.tsx
      • examples/react/start-workos/vite.config.ts
      • examples/react/start-workos/src/routes/_authenticated.tsx
      • examples/react/start-workos/src/routes/__root.tsx
      examples/{react,solid}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Keep example applications under examples/react/ and examples/solid/

      Files:

      • examples/react/start-workos/src/vite-env.d.ts
      • examples/react/start-workos/src/routes/index.tsx
      • examples/react/start-workos/src/app.css
      • examples/react/start-workos/src/routes/api/auth/callback.tsx
      • examples/react/start-workos/src/start.ts
      • examples/react/start-workos/src/routes/logout.tsx
      • examples/react/start-workos/src/routes/_authenticated/account.tsx
      • examples/react/start-workos/src/routeTree.gen.ts
      • examples/react/start-workos/package.json
      • examples/react/start-workos/src/routes/client.tsx
      • examples/react/start-workos/vite.config.ts
      • examples/react/start-workos/src/routes/_authenticated.tsx
      • examples/react/start-workos/src/routes/__root.tsx
      **/src/routes/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Place file-based routes under src/routes/ directories

      Files:

      • examples/react/start-workos/src/routes/index.tsx
      • examples/react/start-workos/src/routes/api/auth/callback.tsx
      • examples/react/start-workos/src/routes/logout.tsx
      • examples/react/start-workos/src/routes/_authenticated/account.tsx
      • examples/react/start-workos/src/routes/client.tsx
      • examples/react/start-workos/src/routes/_authenticated.tsx
      • examples/react/start-workos/src/routes/__root.tsx
      **/package.json

      📄 CodeRabbit inference engine (AGENTS.md)

      Use workspace:* protocol for internal dependencies in package.json files

      Files:

      • packages/start-server-core/package.json
      • examples/react/start-workos/package.json
      packages/{*-start,start-*}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Name and place Start framework packages under packages/-start/ or packages/start-/

      Files:

      • packages/start-server-core/package.json
      🧬 Code graph analysis (7)
      examples/react/start-workos/src/routes/index.tsx (3)
      examples/react/start-workos/src/routes/__root.tsx (1)
      • Route (12-39)
      examples/react/start-workos/src/routes/_authenticated.tsx (1)
      • Route (4-14)
      examples/react/start-workos/src/routes/_authenticated/account.tsx (1)
      • Route (5-27)
      examples/react/start-workos/src/routes/api/auth/callback.tsx (2)
      examples/react/start-workos/src/routes/__root.tsx (1)
      • Route (12-39)
      examples/react/start-workos/src/routes/_authenticated.tsx (1)
      • Route (4-14)
      examples/react/start-workos/src/routes/_authenticated/account.tsx (3)
      examples/react/start-workos/src/routes/__root.tsx (1)
      • Route (12-39)
      examples/react/start-workos/src/routes/_authenticated.tsx (1)
      • Route (4-14)
      examples/react/start-workos/src/routes/index.tsx (1)
      • Route (6-13)
      examples/react/start-workos/src/routeTree.gen.ts (2)
      packages/router-core/src/router.ts (1)
      • Register (97-102)
      examples/react/start-workos/src/router.tsx (1)
      • getRouter (4-11)
      examples/react/start-workos/src/routes/client.tsx (6)
      examples/react/start-workos/src/routes/__root.tsx (1)
      • Route (12-39)
      examples/react/start-workos/src/routes/_authenticated.tsx (1)
      • Route (4-14)
      examples/react/start-workos/src/routes/_authenticated/account.tsx (1)
      • Route (5-27)
      examples/react/start-workos/src/routes/api/auth/callback.tsx (1)
      • Route (4-10)
      examples/react/start-workos/src/routes/index.tsx (1)
      • Route (6-13)
      examples/react/start-workos/src/routes/logout.tsx (1)
      • Route (4-9)
      examples/react/start-workos/src/routes/_authenticated.tsx (3)
      examples/react/start-workos/src/routes/__root.tsx (1)
      • Route (12-39)
      examples/react/start-workos/src/routes/_authenticated/account.tsx (1)
      • Route (5-27)
      examples/react/start-workos/src/routes/index.tsx (1)
      • Route (6-13)
      examples/react/start-workos/src/routes/__root.tsx (1)
      examples/react/start-workos/src/components/sign-in-button.tsx (1)
      • SignInButton (5-21)
      ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
      • GitHub Check: Test
      • GitHub Check: Preview
      🔇 Additional comments (8)
      examples/react/start-workos/vite.config.ts (2)

      21-23: LGTM!

      The ssr.noExternal configuration for @radix-ui/themes is correct. Radix UI components need to be bundled during SSR rather than externalized, as they rely on client-side dependencies that must be transformed.


      5-8: No action required: .env.example and README.md document the required environment variables.

      examples/react/start-workos/src/vite-env.d.ts (1)

      1-6: LGTM!

      The Vite client typings and CSS URL module declaration are correctly configured. This enables TypeScript to properly type CSS imports with the ?url suffix (e.g., import appCssUrl from './app.css?url'), which is used in the root route.

      examples/react/start-workos/src/app.css (1)

      1-1: LGTM!

      The Radix UI themes stylesheet import is correctly configured and will be loaded via the URL import pattern in the root route.

      examples/react/start-workos/src/start.ts (1)

      8-13: LGTM!

      The Start instance configuration correctly integrates the AuthKit middleware. The middleware will run on every server request, providing authentication context to route loaders and server functions.

      examples/react/start-workos/src/routes/logout.tsx (1)

      2-2: LGTM!

      The import change from local implementation to the external SDK is correct and aligns with the PR's objective of using the official AuthKit SDK. The signOut function usage remains unchanged, preserving existing behavior.

      examples/react/start-workos/src/routes/api/auth/callback.tsx (1)

      2-9: LGTM!

      Delegating the OAuth callback handling to handleCallbackRoute from the external SDK simplifies the code significantly. The SDK now handles token exchange, session management, state validation, and redirects, reducing custom implementation complexity and potential security issues.

      packages/start-server-core/package.json (1)

      79-79: Vite devDependency is intentional: start-server-core defines a "build": "vite build" script and includes vite.config.ts, so adding "vite": "^7.1.7" is required.

      Likely an incorrect or invalid review comment.

      examples/react/start-workos/package.json line 21Outdated
      @@ -18,3 +18,4 @@
      1818 "@tanstack/react-router-devtools": "^1.132.47",
      1919 "@tanstack/react-start": "^1.132.47",
      2020 "@workos-inc/node": "^7.45.0",
      21+ "@workos/authkit-tanstack-react-start": "^0.1.0",

      ⚠️ Potential issue | 🔴 Critical

      🧩 Analysis chain

      Verify stability and breaking change expectations for the 0.1.x SDK.

      The @workos/authkit-tanstack-react-start package is at version ^0.1.0, which indicates it's in early development. Pre-1.0 versions may introduce breaking changes in minor/patch releases. Consider pinning to an exact version or documenting this dependency risk.


      🌐 Web query:

      What is the latest stable version of @workos/authkit-tanstack-react-start and its release stability policy?

      💡 Result:

      I couldn't find any published npm package named "@workos/authkit-tanstack-react-start". Searches of npm/GitHub and WorkOS docs show WorkOS publishes AuthKit packages under @workos-inc (e.g. @workos-inc/authkit-react and @workos-inc/authkit-react-router), and the TanStack Start docs include a WorkOS example (not a package with the name you gave). [1][2][3]

      If you meant a different package name, or a workspace/example repo, tell me the exact npm/GitHub package or repo and I’ll look it up. References:

      • WorkOS AuthKit docs and packages. [1]
      • WorkOS GitHub (authkit-react, authkit-nextjs, authkit-react-router). [2]
      • TanStack Start React — WorkOS example (Start + WorkOS). [3]

      Sources: [1] https://workos.com/docs/authkit/react [2] https://github.com/workos [3] https://tanstack.com/start/latest/docs/framework/react/examples/start-workos


      Correct invalid package dependency The dependency "@workos/authkit-tanstack-react-start" isn’t published on npm; WorkOS AuthKit packages live under the @workos-inc scope (e.g. @workos-inc/authkit-react). Update line 21 of examples/react/start-workos/package.json to the correct package name and version.

      🤖 Prompt for AI Agents
      examples/react/start-workos/package.json around line 21: Replace the invalid
      dependency "@workos/authkit-tanstack-react-start" with the correct scoped
      package name and version, e.g. "@workos-inc/authkit-react": "^0.1.0" (or the
      exact published version you need), then save and run npm/yarn install to update
      lockfiles.

      note: we have both the @workos and @workos-inc namespaces on npm. We've been working on a way to transition from @workos-inc to @workos because it's simpler and since this SDK was brand new, I figured I'd just start there. I can accelerate my idea to dual-publish if this is an issue.

      Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

    6. nicknisi(GitHub profile, opens in a new tab)replied on examples/react/start-workos/package.json line 21

      note: we have both the @workos and @workos-inc namespaces on npm. We've been working on a way to transition from @workos-inc to @workos because it's simpler and since this SDK was brand new, I figured I'd just start there. I can accelerate my idea to dual-publish if this is an issue.

    7. coderabbitai[bot](GitHub profile, opens in a new tab)replied on examples/react/start-workos/package.json line 21

      Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

    8. OutdatedResolvedby nicknisi(GitHub profile, opens in a new tab)
    9. Actionable comments posted: 1

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 4a0989764b2e455e90bbe36239f878279e033e2d and a13f1e1a0c05f13fb20004a760f1534146aef64c.

      📒 Files selected for processing (19)
      • examples/react/start-workos/package.json (2 hunks)
      • examples/react/start-workos/src/app.css (1 hunks)
      • examples/react/start-workos/src/authkit/serverFunctions.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/config.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/interfaces.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/session.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/utils.ts (0 hunks)
      • examples/react/start-workos/src/authkit/ssr/workos.ts (0 hunks)
      • examples/react/start-workos/src/routeTree.gen.ts (8 hunks)
      • examples/react/start-workos/src/routes/__root.tsx (3 hunks)
      • examples/react/start-workos/src/routes/_authenticated.tsx (1 hunks)
      • examples/react/start-workos/src/routes/_authenticated/account.tsx (1 hunks)
      • examples/react/start-workos/src/routes/api/auth/callback.tsx (1 hunks)
      • examples/react/start-workos/src/routes/client.tsx (1 hunks)
      • examples/react/start-workos/src/routes/index.tsx (2 hunks)
      • examples/react/start-workos/src/routes/logout.tsx (1 hunks)
      • examples/react/start-workos/src/start.ts (1 hunks)
      • examples/react/start-workos/src/vite-env.d.ts (1 hunks)
      • examples/react/start-workos/vite.config.ts (2 hunks)
      💤 Files with no reviewable changes (6)
      • examples/react/start-workos/src/authkit/ssr/utils.ts
      • examples/react/start-workos/src/authkit/ssr/workos.ts
      • examples/react/start-workos/src/authkit/ssr/config.ts
      • examples/react/start-workos/src/authkit/ssr/interfaces.ts
      • examples/react/start-workos/src/authkit/serverFunctions.ts
      • examples/react/start-workos/src/authkit/ssr/session.ts
      🚧 Files skipped from review as they are similar to previous changes (5)
      • examples/react/start-workos/src/routes/logout.tsx
      • examples/react/start-workos/package.json
      • examples/react/start-workos/src/app.css
      • examples/react/start-workos/src/routes/client.tsx
      • examples/react/start-workos/src/routes/_authenticated.tsx
      🧰 Additional context used
      📓 Path-based instructions (3)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • examples/react/start-workos/src/vite-env.d.ts
      • examples/react/start-workos/src/start.ts
      • examples/react/start-workos/src/routes/_authenticated/account.tsx
      • examples/react/start-workos/src/routes/api/auth/callback.tsx
      • examples/react/start-workos/vite.config.ts
      • examples/react/start-workos/src/routeTree.gen.ts
      • examples/react/start-workos/src/routes/index.tsx
      • examples/react/start-workos/src/routes/__root.tsx
      examples/{react,solid}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Keep example applications under examples/react/ and examples/solid/

      Files:

      • examples/react/start-workos/src/vite-env.d.ts
      • examples/react/start-workos/src/start.ts
      • examples/react/start-workos/src/routes/_authenticated/account.tsx
      • examples/react/start-workos/src/routes/api/auth/callback.tsx
      • examples/react/start-workos/vite.config.ts
      • examples/react/start-workos/src/routeTree.gen.ts
      • examples/react/start-workos/src/routes/index.tsx
      • examples/react/start-workos/src/routes/__root.tsx
      **/src/routes/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Place file-based routes under src/routes/ directories

      Files:

      • examples/react/start-workos/src/routes/_authenticated/account.tsx
      • examples/react/start-workos/src/routes/api/auth/callback.tsx
      • examples/react/start-workos/src/routes/index.tsx
      • examples/react/start-workos/src/routes/__root.tsx
      🧬 Code graph analysis (5)
      examples/react/start-workos/src/routes/_authenticated/account.tsx (3)
      examples/react/start-workos/src/routes/__root.tsx (1)
      • Route (12-39)
      examples/react/start-workos/src/routes/_authenticated.tsx (1)
      • Route (4-14)
      examples/react/start-workos/src/routes/index.tsx (1)
      • Route (6-13)
      examples/react/start-workos/src/routes/api/auth/callback.tsx (2)
      examples/react/start-workos/src/routes/__root.tsx (1)
      • Route (12-39)
      examples/react/start-workos/src/routes/_authenticated.tsx (1)
      • Route (4-14)
      examples/react/start-workos/src/routeTree.gen.ts (2)
      packages/router-core/src/router.ts (1)
      • Register (97-102)
      examples/react/start-workos/src/router.tsx (1)
      • getRouter (4-11)
      examples/react/start-workos/src/routes/index.tsx (5)
      examples/react/start-workos/src/routes/__root.tsx (1)
      • Route (12-39)
      examples/react/start-workos/src/routes/_authenticated.tsx (1)
      • Route (4-14)
      examples/react/start-workos/src/routes/_authenticated/account.tsx (1)
      • Route (5-27)
      examples/react/start-workos/src/routes/api/auth/callback.tsx (1)
      • Route (4-10)
      examples/react/start-workos/src/routes/logout.tsx (1)
      • Route (4-9)
      examples/react/start-workos/src/routes/__root.tsx (2)
      examples/react/start-workos/src/components/sign-in-button.tsx (1)
      • SignInButton (5-21)
      examples/react/start-workos/src/components/footer.tsx (1)
      • Footer (3-32)
      🪛 ESLint
      examples/react/start-workos/src/routes/__root.tsx

      [error] 10-10: ../app.css?url import should occur before type import of react

      (import/order)

      ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
      • GitHub Check: Test
      • GitHub Check: Preview
      🔇 Additional comments (10)
      examples/react/start-workos/vite.config.ts (2)

      5-8: LGTM: dotenv configuration is appropriate for the WorkOS SDK.

      Loading environment variables at the module level ensures they're available before the SDK initializes.


      21-23: LGTM: SSR configuration correctly handles Radix UI.

      Including @radix-ui/themes in noExternal ensures the theme components are properly bundled for server-side rendering.

      examples/react/start-workos/src/routes/_authenticated/account.tsx (1)

      7-26: LGTM: Loader correctly migrated to use SDK.

      The loader properly uses getAuth() from the SDK and correctly handles optional role and permissions fields. The runtime checks ensure proper handling when these properties are absent.

      examples/react/start-workos/src/vite-env.d.ts (1)

      1-6: LGTM: TypeScript declaration correctly enables CSS URL imports.

      This declaration allows importing CSS files as URLs (e.g., import url from './style.css?url'), which is used in the root route to add a stylesheet link.

      examples/react/start-workos/src/start.ts (1)

      1-13: LGTM: Start configuration correctly integrates AuthKit middleware.

      The middleware setup ensures authentication context is available for all server functions like getAuth() and getSignInUrl() throughout the application.

      examples/react/start-workos/src/routes/api/auth/callback.tsx (1)

      1-10: LGTM: Callback route properly delegates to SDK.

      Replacing the custom callback implementation with handleCallbackRoute from the SDK simplifies the code and ensures the example follows the recommended approach.

      examples/react/start-workos/src/routes/index.tsx (2)

      3-12: LGTM: Route correctly migrated to use SDK.

      The loader properly uses getAuth() and getSignInUrl() from the SDK, following the same pattern as other routes in this migration.


      24-24: Minor UI text improvement.

      Updated text more specifically identifies this as a TanStack Start application.

      examples/react/start-workos/src/routes/__root.tsx (2)

      5-6: LGTM: Root route properly migrated to use SDK.

      The loader correctly uses getAuth() and getSignInUrl() from the SDK, replacing the previous beforeLoad approach. This ensures authentication data is available during client-side navigation.

      Also applies to: 28-36


      45-87: LGTM: AuthKitProvider correctly wraps the application.

      The AuthKitProvider integration enables client-side auth state management throughout the component tree, which is essential for the SDK's client-side functionality.

      Resolvedby coderabbitai[bot](GitHub profile, opens in a new tab)
    10. nicknisi(GitHub profile, opens in a new tab)replied on packages/start-server-core/package.json line 79

      I think at the time I was having build issues without that - I rebased and tried again and was able to remove it. Thanks!

    11. Actionable comments posted: 0

      🧹 Nitpick comments (2)
      examples/react/start-workos/src/routes/__root.tsx (2)

      28-31: Make loader calls concurrent or skip sign‑in URL when authenticated.

      Both calls are independent; either run them together or avoid fetching the URL if a user exists.

      Option A — concurrent:

      -  loader: async () => {
      -    // getAuth() is a server function - works during client-side navigation
      -    const { user } = await getAuth();
      -    const url = await getSignInUrl();
      -    return { user, url };
      -  },
      +  loader: async () => {
      +    const [{ user }, url] = await Promise.all([getAuth(), getSignInUrl()]);
      +    return { user, url };
      +  },

      Option B — skip when logged in:

      -  loader: async () => {
      -    const { user } = await getAuth();
      -    const url = await getSignInUrl();
      -    return { user, url };
      -  },
      +  loader: async () => {
      +    const { user } = await getAuth();
      +    const url = user ? '' : await getSignInUrl();
      +    return { user, url };
      +  },

      45-87: Hydration not supported; retain layout improvements.

      AuthKitProvider does not expose initialUser or hydrate props—it obtains the user from the client flow and performs its own fetch. Remove the hydration suggestion.

      The other recommendations remain valid:

      • Suspense around SignInButton is unnecessary; consider moving it around <Outlet /> (which is more likely to suspend) or remove it.
      • Prefer min-height: 100dvh over height="100vh" for mobile browser chrome.

      Example tweaks:

      -            <Flex direction="column" gap="5" p="5" height="100vh">
      +            <Flex direction="column" gap="5" p="5" style={{ minHeight: '100dvh' }}>
      ...
      -                        <Suspense fallback={<div>Loading...</div>}>
      -                          <SignInButton user={user} url={url} />
      -                        </Suspense>
      +                        <SignInButton user={user} url={url} />
      ...
      -                      <main>
      -                        <Outlet />
      -                      </main>
      +                      <main>
      +                        <Suspense fallback={<div>Loading...</div>}>
      +                          <Outlet />
      +                        </Suspense>
      +                      </main>
      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between b0951c495a916e9e13e96847777544ce88684d9f and 1608437ac672d866ef2146326ddc73b7cd213610.

      📒 Files selected for processing (1)
      • examples/react/start-workos/src/routes/__root.tsx (3 hunks)
      🧰 Additional context used
      📓 Path-based instructions (3)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • examples/react/start-workos/src/routes/__root.tsx
      **/src/routes/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Place file-based routes under src/routes/ directories

      Files:

      • examples/react/start-workos/src/routes/__root.tsx
      examples/{react,solid}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Keep example applications under examples/react/ and examples/solid/

      Files:

      • examples/react/start-workos/src/routes/__root.tsx
      🧬 Code graph analysis (1)
      examples/react/start-workos/src/routes/__root.tsx (1)
      examples/react/start-workos/src/components/sign-in-button.tsx (1)
      • SignInButton (5-21)
      ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
      • GitHub Check: Test
      🔇 Additional comments (4)
      examples/react/start-workos/src/routes/__root.tsx (4)

      5-7: Good server/client split on imports.

      Using server functions from @workos/authkit-tanstack-react-start and the client provider from its /client entry is correct for Start’s bundling model.


      9-10: Import order fixed.

      app.css?url now precedes the type import, resolving the prior import/order lint complaint.


      26-26: Stylesheet link wiring looks right.

      Referencing appCssUrl via links ensures SSR-safe stylesheet injection.


      94-94: Good accessibility default.

      <html lang="en"> is a solid baseline for a11y and SEO.

    12. @schiller-manuel It would be great to see this merged sooner rather than later, so developers have clarity on current best practices and are not confused by outdated docs.

      This is now the preferred way of using WorkOS and is being actively developed by @nicknisi and the WorkOS team. On Dec 15 2025, related templates and examples repos from WorkOS were archived in favor of this SDK, and it also aligns with @convex-dev/workos-authkit.

Sign in to join this conversation.