chore(tanstack-react-start): Reuse existing auth object from server handler (#6595)

Author: wobsoriano

.changeset/itchy-zoos-shake.md

@@ -0,0 +1,25 @@
+---
+"@clerk/tanstack-react-start": minor
+---
+
+Reuses existing `Auth` object from the server handler when using `getAuth()`
+
+The `createClerkHandler` helper now returns a Promise and requires awaiting during setup to ensure authentication context is available at the earliest possible point in the request lifecycle, before any router loaders or server functions execute
+
+```ts
+// server.ts
+import { createStartHandler, defineHandlerCallback, defaultStreamHandler } from '@tanstack/react-start/server';
+import { createRouter } from './router';
+import { createClerkHandler } from '@clerk/tanstack-react-start/server';
+
+const handlerFactory = createClerkHandler(
+  createStartHandler({
+    createRouter,
+  }),
+);
+
+export default defineHandlerCallback(async event => {
+  const startHandler = await handlerFactory(defaultStreamHandler); // awaited
+  return startHandler(event);
+});
+```

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

@@ -9,9 +9,9 @@
     "start": "vite"
   },
   "dependencies": {
-    "@tanstack/react-router": "1.128.0",
-    "@tanstack/react-router-devtools": "1.128.0",
-    "@tanstack/router-plugin": "1.128.0",
+    "@tanstack/react-router": "1.131.27",
+    "@tanstack/react-router-devtools": "1.131.27",
+    "@tanstack/router-plugin": "1.131.27",
     "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.128.0",
-    "@tanstack/react-router-devtools": "1.128.0",
-    "@tanstack/react-start": "1.128.0",
+    "@tanstack/react-router": "1.131.27",
+    "@tanstack/react-router-devtools": "1.131.27",
+    "@tanstack/react-start": "1.131.27",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "tailwind-merge": "^2.5.4"

integration/templates/tanstack-react-start/src/server.tsx

@@ -1,9 +1,14 @@
-import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server';
+import { createStartHandler, defineHandlerCallback, defaultStreamHandler } from '@tanstack/react-start/server';
 import { createRouter } from './router';
 import { createClerkHandler } from '@clerk/tanstack-react-start/server';
 
-export default createClerkHandler(
+const handlerFactory = createClerkHandler(
   createStartHandler({
     createRouter,
   }),
-)(defaultStreamHandler);
+);
+
+export default defineHandlerCallback(async event => {
+  const startHandler = await handlerFactory(defaultStreamHandler);
+  return startHandler(event);
+});

packages/tanstack-react-start/README.md

@@ -41,122 +41,13 @@
 
 ### Installation
 
-```sh
-npm install @clerk/tanstack-react-start
-```
+The fastest way to get started with Clerk is by following the [TanStack React Start Quickstart](https://clerk.com/docs/quickstarts/tanstack-react-start?utm_source=github&utm_medium=clerk_tanstack_react_start).
+
+You'll learn how to install `@clerk/tanstack-react-start`, set up your environment keys, configure `createClerkHandler` and protect your pages.
 
 ## Usage
 
-Make sure the following environment variables are set in a `.env` file:
-
-```sh
-CLERK_PUBLISHABLE_KEY=pk_test_xxx
-CLERK_SECRET_KEY=sk_test_xxx
-```
-
-You can get these from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) screen in your Clerk dashboard.
-
-To initialize Clerk with your TanStack Start application, you will need to make one modification to `app/routes/_root.tsx`. Wrap the children of the `RootComponent` with `<ClerkProvider/>`
-
-```tsx
-import { ClerkProvider } from '@clerk/tanstack-react-start'
-import { createRootRoute } from '@tanstack/react-router'
-import { Link, Outlet } from '@tanstack/react-router'
-import { TanStackRouterDevtools } from '@tanstack/router-devtools'
-import { Body, Head, Html, Meta, Scripts } from '@tanstack/start'
-import * as React from 'react'
-import { DefaultCatchBoundary } from '~/components/DefaultCatchBoundary'
-import { NotFound } from '~/components/NotFound'
-
-export const Route = createRootRoute({
-  meta: () => [
-    {
-      charSet: 'utf-8',
-    },
-    {
-      name: 'viewport',
-      content: 'width=device-width, initial-scale=1',
-    },
-  ],
-  errorComponent: (props) => {
-    return (
-      <RootDocument>
-        <DefaultCatchBoundary {...props} />
-      </RootDocument>
-    )
-  },
-  notFoundComponent: () => <NotFound />,
-  component: RootComponent,
-})
-
-function RootComponent() {
-  return (
-    <ClerkProvider>
-      <RootDocument>
-          <Outlet />
-      </RootDocument>
-    </ClerkProvider>
-  )
-}
-
-function RootDocument({ children }: { children: React.ReactNode }) { ... }
-```
-
-### Setup `clerkHandler` in the SSR entrypoint
-
-You will also need to make on more modification to you SSR entrypoint (default: `app/ssr.tsx`):
-
-- Wrap the `createStartHandler` with `createClerkHandler`
-
-```tsx
-import { createStartHandler, defaultStreamHandler } from '@tanstack/start/server';
-import { getRouterManifest } from '@tanstack/start/router-manifest';
-import { createRouter } from './router';
-import { createClerkHandler } from '@clerk/tanstack-react-start/server';
-
-const handler = createStartHandler({
-  createRouter,
-  getRouterManifest,
-});
-
-const clerkHandler = createClerkHandler(handler);
-
-/*
- * // You can also override Clerk options by passing an object as second argument
- * const clerkHandler = createClerkHandler(handler, {
- *   afterSignInUrl: '/dashboard',
- * });
- */
-
-export default clerkHandler(defaultStreamHandler);
-```
-
-After those changes are made, you can use Clerk components in your routes.
-
-For example, in `app/routes/index.tsx`:
-
-```tsx
-import { SignIn, SignedIn, SignedOut, UserButton } from '@clerk/tanstack-react-start';
-import { createFileRoute } from '@tanstack/react-router';
-
-export const Route = createFileRoute('/')({
-  component: Home,
-});
-
-function Home() {
-  return (
-    <div className='p-2'>
-      <h1>Hello Clerk!</h1>
-      <SignedIn>
-        <UserButton />
-      </SignedIn>
-      <SignedOut>
-        <SignIn />
-      </SignedOut>
-    </div>
-  );
-}
-```
+For further information, guides, and examples visit the [TanStack React Start reference documentation](https://clerk.com/docs/references/tanstack-react-start/overview?utm_source=github&utm_medium=clerk_tanstack_react_start).
 
 ## Support
 

packages/tanstack-react-start/package.json

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

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

@@ -1,16 +1,9 @@
 import { createClerkClient } from '@clerk/backend';
-import type { AuthenticatedState, AuthenticateRequestOptions, UnauthenticatedState } from '@clerk/backend/internal';
-import { AuthStatus, constants } from '@clerk/backend/internal';
-import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
+import type { AuthenticateRequestOptions, RequestState } from '@clerk/backend/internal';
 
-import { errorThrower } from '../utils';
-import { ClerkHandshakeRedirect } from './errors';
 import { patchRequest } from './utils';
 
-export async function authenticateRequest(
-  request: Request,
-  opts: AuthenticateRequestOptions,
-): Promise<AuthenticatedState | UnauthenticatedState> {
+export async function authenticateRequest(request: Request, opts: AuthenticateRequestOptions): Promise<RequestState> {
   const { audience, authorizedParties } = opts;
 
   const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey, acceptsToken, machineSecretKey } =
@@ -37,22 +30,5 @@ export async function authenticateRequest(
     acceptsToken,
   });
 
-  const locationHeader = requestState.headers.get(constants.Headers.Location);
-  if (locationHeader) {
-    handleNetlifyCacheInDevInstance({
-      locationHeader,
-      requestStateHeaders: requestState.headers,
-      publishableKey: requestState.publishableKey,
-    });
-
-    // triggering a handshake redirect
-    throw new ClerkHandshakeRedirect(307, requestState.headers);
-  }
-
-  if (requestState.status === AuthStatus.Handshake) {
-    // eslint-disable-next-line @typescript-eslint/only-throw-error
-    throw errorThrower.throw('Clerk: unexpected handshake without redirect');
-  }
-
   return requestState;
 }

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

@@ -1,29 +1,25 @@
 import type { AuthenticateRequestOptions, GetAuthFn } from '@clerk/backend/internal';
 import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
+import { getContext } from '@tanstack/react-start/server';
 
 import { errorThrower } from '../utils';
-import { noFetchFnCtxPassedInGetAuth } from '../utils/errors';
-import { authenticateRequest } from './authenticateRequest';
-import { loadOptions } from './loadOptions';
-import type { LoaderOptions } from './types';
+import { clerkHandlerNotConfigured, noFetchFnCtxPassedInGetAuth } from '../utils/errors';
 
-type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] } & Pick<LoaderOptions, 'secretKey'>;
+type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
 
 export const getAuth: GetAuthFn<Request, true> = (async (request: Request, opts?: GetAuthOptions) => {
   if (!request) {
     return errorThrower.throw(noFetchFnCtxPassedInGetAuth);
   }
 
-  const { acceptsToken, ...restOptions } = opts || {};
+  const authObjectFn = getContext('auth');
 
-  const loadedOptions = loadOptions(request, restOptions);
-
-  const requestState = await authenticateRequest(request, {
-    ...loadedOptions,
-    acceptsToken: 'any',
-  });
+  if (!authObjectFn) {
+    return errorThrower.throw(clerkHandlerNotConfigured);
+  }
 
-  const authObject = requestState.toAuth();
+  // We're keeping it a promise for now to minimize breaking changes
+  const authObject = await Promise.resolve(authObjectFn());
 
-  return getAuthObjectForAcceptedToken({ authObject, acceptsToken });
+  return getAuthObjectForAcceptedToken({ authObject, acceptsToken: opts?.acceptsToken });
 }) as GetAuthFn<Request, true>;

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

@@ -1,8 +1,16 @@
+import { AuthStatus, constants } from '@clerk/backend/internal';
+import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { AnyRouter } from '@tanstack/react-router';
-import type { CustomizeStartHandler, HandlerCallback, RequestHandler } from '@tanstack/react-start/server';
+import {
+  type CustomizeStartHandler,
+  getEvent,
+  getWebRequest,
+  type HandlerCallback,
+  type RequestHandler,
+} from '@tanstack/react-start/server';
 
+import { errorThrower } from '../utils';
 import { authenticateRequest } from './authenticateRequest';
-import { ClerkHandshakeRedirect } from './errors';
 import { loadOptions } from './loadOptions';
 import type { LoaderOptions } from './types';
 import { getResponseClerkState } from './utils';
@@ -11,41 +19,52 @@ export function createClerkHandler<TRouter extends AnyRouter>(
   eventHandler: CustomizeStartHandler<TRouter>,
   clerkOptions: LoaderOptions = {},
 ) {
-  return (cb: HandlerCallback<TRouter>): RequestHandler => {
-    return eventHandler(async ({ request, router, responseHeaders }) => {
-      try {
-        const loadedOptions = loadOptions(request, clerkOptions);
+  return async (cb: HandlerCallback<TRouter>): Promise<RequestHandler> => {
+    const request = getWebRequest();
+    const event = getEvent();
+    const loadedOptions = loadOptions(request, clerkOptions);
 
-        const requestState = await authenticateRequest(request, {
-          ...loadedOptions,
-          acceptsToken: 'any',
-        });
+    const requestState = await authenticateRequest(request, {
+      ...loadedOptions,
+      acceptsToken: 'any',
+    });
 
-        const { clerkInitialState, headers } = getResponseClerkState(requestState, loadedOptions);
+    // Set auth object here so it is available immediately in server functions via getAuth()
+    event.context.auth = () => requestState.toAuth();
 
-        // Merging the TanStack router context with the Clerk context and loading the router
-        router.update({
-          context: { ...router.options.context, clerkInitialState },
+    return eventHandler(async ({ request, router, responseHeaders }) => {
+      const locationHeader = requestState.headers.get(constants.Headers.Location);
+      if (locationHeader) {
+        handleNetlifyCacheInDevInstance({
+          locationHeader,
+          requestStateHeaders: requestState.headers,
+          publishableKey: requestState.publishableKey,
         });
 
-        headers.forEach((value, key) => {
-          responseHeaders.set(key, value);
+        return new Response(null, {
+          status: 307,
+          headers: requestState.headers,
         });
+      }
 
-        await router.load();
-      } catch (error) {
-        if (error instanceof ClerkHandshakeRedirect) {
-          // returning the response
-          return new Response(null, {
-            status: error.status,
-            headers: error.headers,
-          });
-        }
-
-        // rethrowing the error if it is not a Response
-        throw error;
+      if (requestState.status === AuthStatus.Handshake) {
+        // eslint-disable-next-line @typescript-eslint/only-throw-error
+        throw errorThrower.throw('Clerk: unexpected handshake without redirect');
       }
 
+      const { clerkInitialState, headers } = getResponseClerkState(requestState, loadedOptions);
+
+      // Merging the TanStack router context with the Clerk context and loading the router
+      router.update({
+        context: { ...router.options.context, clerkInitialState },
+      });
+
+      headers.forEach((value, key) => {
+        responseHeaders.set(key, value);
+      });
+
+      await router.load();
+
       return cb({ request, router, responseHeaders });
     });
   };