fix(tanstack-react-start): Handle serialization issue when doing handshake

.changeset/fifty-buses-fix.md

@@ -0,0 +1,6 @@
+---
+'@clerk/tanstack-react-start': minor
+---
+
+- Fixes serialization errors during handshake
+- Bump `@tanstack/react-start` and `@tanstack/react-router` peer dependency to 1.127.0

integration/templates/tanstack-react-router/package.json

@@ -9,9 +9,9 @@
     "start": "vite"
   },
   "dependencies": {
-    "@tanstack/react-router": "^1.121.27",
-    "@tanstack/react-router-devtools": "^1.121.27",
-    "@tanstack/router-plugin": "^1.121.27",
+    "@tanstack/react-router": "^1.128.0",
+    "@tanstack/react-router-devtools": "^1.128.0",
+    "@tanstack/router-plugin": "^1.128.0",
     "react": "18.3.1",
     "react-dom": "18.3.1"
   },

integration/templates/tanstack-react-start/package.json

@@ -8,9 +8,9 @@
     "start": "vite start --port=$PORT"
   },
   "dependencies": {
-    "@tanstack/react-router": "^1.121.27",
-    "@tanstack/react-router-devtools": "^1.121.27",
-    "@tanstack/react-start": "^1.121.28",
+    "@tanstack/react-router": "^1.128.0",
+    "@tanstack/react-router-devtools": "^1.128.0",
+    "@tanstack/react-start": "^1.128.0",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "tailwind-merge": "^2.5.4"

integration/templates/tanstack-react-start/src/routes/user.tsx

@@ -0,0 +1,29 @@
+import { createFileRoute, redirect } from '@tanstack/react-router';
+import { createServerFn } from '@tanstack/react-start';
+import { getAuth } from '@clerk/tanstack-react-start/server';
+import { getWebRequest } from '@tanstack/react-start/server';
+
+const fetchClerkAuth = createServerFn({ method: 'GET' }).handler(async () => {
+  const request = getWebRequest();
+  if (!request) throw new Error('No request found');
+
+  const { userId } = await getAuth(request);
+
+  return {
+    userId,
+  };
+});
+
+export const Route = createFileRoute('/')({
+  component: Page,
+  beforeLoad: async () => await fetchClerkAuth(),
+  loader: async ({ context }) => {
+    return { userId: context.userId };
+  },
+});
+
+function Page() {
+  const state = Route.useLoaderData();
+
+  return state.userId ? <h1>Welcome! Your ID is {state.userId}!</h1> : <h1>You are not signed in</h1>;
+}

integration/tests/tanstack-start/basic.test.ts

@@ -1,3 +1,4 @@
+import type { User } from '@clerk/backend';
 import { expect, test } from '@playwright/test';
 
 import { appConfigs } from '../../presets';
@@ -16,6 +17,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })(
     test.describe.configure({ mode: 'parallel' });
 
     let fakeUser: FakeUser;
+    let bapiUser: User;
 
     test.beforeAll(async () => {
       const u = createTestUtils({ app });
@@ -24,7 +26,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })(
         withPhoneNumber: true,
         withUsername: true,
       });
-      await u.services.users.createBapiUser(fakeUser);
+      bapiUser = await u.services.users.createBapiUser(fakeUser);
     });
 
     test.afterAll(async () => {
@@ -72,6 +74,25 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })(
       expect(clerkInitialState !== undefined).toBeTruthy();
     });
 
+    test('retrieve auth state in server functions', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+
+      await u.page.goToRelative('/user');
+
+      await expect(u.page.getByText('You are not signed in')).toBeVisible();
+
+      await u.po.signIn.goTo();
+
+      await u.po.signIn.setIdentifier(fakeUser.email);
+      await u.po.signIn.setPassword(fakeUser.password);
+      await u.po.signIn.continue();
+      await u.po.expect.toBeSignedIn();
+
+      await u.page.goToRelative('/user');
+
+      await expect(u.page.getByText(`Welcome! Your ID is ${bapiUser.id}!`)).toBeVisible();
+    });
+
     test('clerk handler sets headers', async ({ page, context }) => {
       const u = createTestUtils({ app, page, context });
       const r = await u.po.signIn.goTo();

packages/tanstack-react-start/package.json

@@ -74,13 +74,13 @@
     "tslib": "catalog:repo"
   },
   "devDependencies": {
-    "@tanstack/react-router": "^1.121.41",
-    "@tanstack/react-start": "^1.121.41",
+    "@tanstack/react-router": "^1.127.0",
+    "@tanstack/react-start": "^1.127.0",
     "esbuild-plugin-file-path-extensions": "^2.1.4"
   },
   "peerDependencies": {
-    "@tanstack/react-router": "^1.121.0",
-    "@tanstack/react-start": "^1.121.0",
+    "@tanstack/react-router": "^1.127.0",
+    "@tanstack/react-start": "^1.127.0",
     "react": "catalog:peer-react",
     "react-dom": "catalog:peer-react"
   },

packages/tanstack-react-start/src/server/authenticateRequest.ts

@@ -4,6 +4,7 @@ import { AuthStatus, constants } from '@clerk/backend/internal';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 
 import { errorThrower } from '../utils';
+import { ClerkHandshakeRedirect } from './errors';
 import { patchRequest } from './utils';
 
 export async function authenticateRequest(
@@ -41,9 +42,9 @@ export async function authenticateRequest(
       requestStateHeaders: requestState.headers,
       publishableKey: requestState.publishableKey,
     });
+
     // triggering a handshake redirect
-    // eslint-disable-next-line @typescript-eslint/only-throw-error
-    throw new Response(null, { status: 307, headers: requestState.headers });
+    throw new ClerkHandshakeRedirect(307, requestState.headers);
   }
 
   if (requestState.status === AuthStatus.Handshake) {

packages/tanstack-react-start/src/server/errors.ts

@@ -0,0 +1,11 @@
+export class ClerkHandshakeRedirect extends Error {
+  constructor(
+    public status: number,
+    public headers: Headers,
+  ) {
+    super('Clerk handshake redirect required');
+    this.name = 'ClerkHandshakeRedirect';
+    this.status = status;
+    this.headers = headers;
+  }
+}

packages/tanstack-react-start/src/server/middlewareHandler.ts

@@ -2,6 +2,7 @@ import type { AnyRouter } from '@tanstack/react-router';
 import type { CustomizeStartHandler, HandlerCallback, RequestHandler } from '@tanstack/react-start/server';
 
 import { authenticateRequest } from './authenticateRequest';
+import { ClerkHandshakeRedirect } from './errors';
 import { loadOptions } from './loadOptions';
 import type { LoaderOptions } from './types';
 import { getResponseClerkState } from './utils';
@@ -33,9 +34,12 @@ export function createClerkHandler<TRouter extends AnyRouter>(
 
         await router.load();
       } catch (error) {
-        if (error instanceof Response) {
+        if (error instanceof ClerkHandshakeRedirect) {
           // returning the response
-          return error;
+          return new Response(null, {
+            status: error.status,
+            headers: error.headers,
+          });
         }
 
         // rethrowing the error if it is not a Response