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

.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 });
  });
  };

.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 });
  });
  };

.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 });
  });
  };

.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 });
  });
  };

.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 });
  });
  };

.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 });
  });
  };

.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 });
  });
  };

.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 });
  });
  };