clerk · wobsoriano · Sep 25, 2025 · Sep 26, 2025 · Sep 26, 2025 · Sep 26, 2025
diff --git a/.changeset/spotty-cooks-march.md b/.changeset/spotty-cooks-march.md
@@ -0,0 +1,70 @@
+---
+"@clerk/tanstack-react-start": minor
+---
+
+Added support for [TanStack Start v1 RC](https://tanstack.com/blog/announcing-tanstack-start-v1)! Includes a new `clerkMiddleware()` global middleware replacing the custom server handler.
+
+Usage:
+
+1. Create a `src/start.ts` file and add `clerkMiddleware()` to the list of request middlewares:
+
+```ts
+// src/start.ts
+import { clerkMiddleware } from '@clerk/tanstack-react-start/server'
+import { createStart } from '@tanstack/react-start'
+
+export const startInstance = createStart(() => {
+  return {
+    requestMiddleware: [clerkMiddleware()],
+  }
+})
+```
+
+2. Add `<ClerkProvider>` to your root route
+
+```tsx
+// src/routes/__root.tsx
+import { ClerkProvider } from '@clerk/tanstack-react-start'
+
+export const Route = createRootRoute({...})
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <ClerkProvider>
+      <html>
+        <head>
+          <HeadContent />
+        </head>
+        <body>
+          {children}
+          <Scripts />
+        </body>
+      </html>
+    </ClerkProvider>
+  )
+}
+```
+
+The `getAuth()` helper can now be called within server routes and functions, without passing a Request object:
+
+```ts
+const authStateFn = createServerFn().handler(async () => {
+  const { userId } = await getAuth()
+
+  if (!userId) {
+    throw redirect({
+      to: '/sign-in',
+    })
+  }
+
+  return { userId }
+})
+
+export const Route = createFileRoute('/')({
+  component: Home,
+  beforeLoad: async () => await authStateFn(),
+  loader: async ({ context }) => {
+    return { userId: context.userId }
+  },
+})
+```
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -292,7 +292,7 @@ jobs:
             'astro',
             'expo-web',
             'tanstack-react-start',
-            'tanstack-react-router',
+            # 'tanstack-react-router',
             'vue',
             'nuxt',
             'react-router',

diff --git a/integration/templates/tanstack-react-start/package.json b/integration/templates/tanstack-react-start/package.json
@@ -8,9 +8,9 @@
     "start": "vite start --port=$PORT"
   },
   "dependencies": {
-    "@tanstack/react-router": "1.131.27",
-    "@tanstack/react-router-devtools": "1.131.27",
-    "@tanstack/react-start": "1.131.27",
+    "@tanstack/react-router": "1.132.31",
+    "@tanstack/react-router-devtools": "1.132.31",
+    "@tanstack/react-start": "1.132.31",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "tailwind-merge": "^2.5.4"

diff --git a/integration/templates/tanstack-react-start/src/router.tsx b/integration/templates/tanstack-react-start/src/router.tsx
@@ -1,8 +1,8 @@
-import { createRouter as createTanStackRouter } from '@tanstack/react-router';
+import { createRouter } from '@tanstack/react-router';
 import { routeTree } from './routeTree.gen';
 
-export function createRouter() {
-  const router = createTanStackRouter({
+export function getRouter() {
+  const router = createRouter({
     routeTree,
     defaultPreload: 'intent',
     defaultErrorComponent: err => <p>{err.error.stack}</p>,
@@ -15,6 +15,6 @@ export function createRouter() {
 
 declare module '@tanstack/react-router' {
   interface Register {
-    router: ReturnType<typeof createRouter>;
+    router: ReturnType<typeof getRouter>;
   }
 }
diff --git a/integration/templates/tanstack-react-start/src/routes/user.tsx b/integration/templates/tanstack-react-start/src/routes/user.tsx
@@ -1,13 +1,9 @@
 import { createFileRoute, redirect } from '@tanstack/react-router';
 import { createServerFn } from '@tanstack/react-start';
 import { getAuth } from '@clerk/tanstack-react-start/server';
-import { getWebRequest } from '@tanstack/react-start/server';
 
 const fetchClerkAuth = createServerFn({ method: 'GET' }).handler(async () => {
-  const request = getWebRequest();
-  if (!request) throw new Error('No request found');
-
-  const { userId } = await getAuth(request);
+  const { userId } = await getAuth();
 
   return {
     userId,

diff --git a/integration/templates/tanstack-react-start/src/server.tsx b/integration/templates/tanstack-react-start/src/server.tsx
diff --git a/integration/templates/tanstack-react-start/src/start.ts b/integration/templates/tanstack-react-start/src/start.ts
@@ -0,0 +1,8 @@
+import { clerkMiddleware } from '@clerk/tanstack-react-start/server';
+import { createStart } from '@tanstack/react-start';
+
+export const startInstance = createStart(() => {
+  return {
+    requestMiddleware: [clerkMiddleware()],
+  };
+});
diff --git a/packages/tanstack-react-start/package.json b/packages/tanstack-react-start/package.json
@@ -76,13 +76,13 @@
     "tslib": "catalog:repo"
   },
   "devDependencies": {
-    "@tanstack/react-router": "1.131.49",
-    "@tanstack/react-start": "1.131.49",
+    "@tanstack/react-router": "1.132.0",
+    "@tanstack/react-start": "1.132.0",
     "esbuild-plugin-file-path-extensions": "^2.1.4"
   },
   "peerDependencies": {
-    "@tanstack/react-router": "^1.131.0 <1.132.0",
-    "@tanstack/react-start": "^1.131.0 <1.132.0",
+    "@tanstack/react-router": "^1.132.0",
+    "@tanstack/react-start": "^1.132.0",
     "react": "catalog:peer-react",
     "react-dom": "catalog:peer-react"
   },

diff --git a/packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -69,7 +69,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
 exports[`server public exports > should not change unexpectedly 1`] = `
 [
   "clerkClient",
-  "createClerkHandler",
+  "clerkMiddleware",
   "getAuth",
 ]
 `;

diff --git a/packages/tanstack-react-start/src/client/ClerkProvider.tsx b/packages/tanstack-react-start/src/client/ClerkProvider.tsx
@@ -1,5 +1,6 @@
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
-import { ScriptOnce, useRouteContext } from '@tanstack/react-router';
+import { ScriptOnce } from '@tanstack/react-router';
+import { getGlobalStartContext } from '@tanstack/react-start';
 import { useEffect } from 'react';
 
 import { isClient } from '../utils';
@@ -19,15 +20,14 @@ const awaitableNavigateRef: { current: ReturnType<typeof useAwaitableNavigate> |
 
 export function ClerkProvider({ children, ...providerProps }: TanstackStartClerkProviderProps): JSX.Element {
   const awaitableNavigate = useAwaitableNavigate();
-  const routerContext = useRouteContext({
-    strict: false,
-  });
+  // @ts-expect-error: Untyped internal Clerk initial state
+  const clerkInitialState = getGlobalStartContext()?.clerkInitialState ?? {};
 
   useEffect(() => {
     awaitableNavigateRef.current = awaitableNavigate;
   }, [awaitableNavigate]);
 
-  const clerkInitState = isClient() ? (window as any).__clerk_init_state : routerContext?.clerkInitialState;
+  const clerkInitState = isClient() ? (window as any).__clerk_init_state : clerkInitialState;
 
   const { clerkSsrState, ...restInitState } = pickFromClerkInitState(clerkInitState?.__internal_clerk_state);
 
@@ -38,7 +38,7 @@ export function ClerkProvider({ children, ...providerProps }: TanstackStartClerk
 
   return (
     <>
-      <ScriptOnce>{`window.__clerk_init_state = ${JSON.stringify(routerContext?.clerkInitialState)};`}</ScriptOnce>
+      <ScriptOnce>{`window.__clerk_init_state = ${JSON.stringify(clerkInitialState)};`}</ScriptOnce>
       <ClerkOptionsProvider options={mergedProps}>
         <ReactClerkProvider
           initialState={clerkSsrState}

diff --git a/packages/tanstack-react-start/src/server/authenticateRequest.ts b/packages/tanstack-react-start/src/server/authenticateRequest.ts
diff --git a/packages/tanstack-react-start/src/server/clerkMiddleware.ts b/packages/tanstack-react-start/src/server/clerkMiddleware.ts
@@ -0,0 +1,54 @@
+import type { RequestState } from '@clerk/backend/internal';
+import { AuthStatus, constants } from '@clerk/backend/internal';
+import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
+import type { PendingSessionOptions } from '@clerk/types';
+import type { AnyRequestMiddleware } from '@tanstack/react-start';
+import { createMiddleware, json } from '@tanstack/react-start';
+
+import { clerkClient } from './clerkClient';
+import { loadOptions } from './loadOptions';
+import type { ClerkMiddlewareOptions } from './types';
+import { getResponseClerkState } from './utils';
+
+export const clerkMiddleware = (options?: ClerkMiddlewareOptions): AnyRequestMiddleware => {
+  return createMiddleware().server(async args => {
+    const loadedOptions = loadOptions(args.request, options);
+    const requestState = await clerkClient().authenticateRequest(args.request, {
+      ...loadedOptions,
+      acceptsToken: 'any',
+    });
+
+    const locationHeader = requestState.headers.get(constants.Headers.Location);
+    if (locationHeader) {
+      handleNetlifyCacheInDevInstance({
+        locationHeader,
+        requestStateHeaders: requestState.headers,
+        publishableKey: requestState.publishableKey,
+      });
+      // Trigger a handshake redirect
+      // eslint-disable-next-line @typescript-eslint/only-throw-error
+      throw json(null, { status: 307, headers: requestState.headers });
+    }
+
+    if (requestState.status === AuthStatus.Handshake) {
+      throw new Error('Clerk: handshake status without redirect');
+    }
+
+    const clerkInitialState = getResponseClerkState(requestState as RequestState, loadedOptions);
+
+    const result = await args.next({
+      context: {
+        clerkInitialState,
+        auth: (opts?: PendingSessionOptions) => requestState.toAuth(opts),
+      },
+    });
+
+    if (requestState.headers) {
+      requestState.headers.forEach((value, key) => {
+        result.response.headers.append(key, value);
+      });
+    }
+
+    return result;
+  });
+};
diff --git a/packages/tanstack-react-start/src/server/errors.ts b/packages/tanstack-react-start/src/server/errors.ts
diff --git a/packages/tanstack-react-start/src/server/getAuth.ts b/packages/tanstack-react-start/src/server/getAuth.ts
@@ -1,23 +1,21 @@
-import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
+import type { SessionAuthObject } from '@clerk/backend';
+import type { AuthOptions, GetAuthFnNoRequest } from '@clerk/backend/internal';
 import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
-import { getContext } from '@tanstack/react-start/server';
+import { getGlobalStartContext } from '@tanstack/react-start';
 
 import { errorThrower } from '../utils';
-import { clerkHandlerNotConfigured, noFetchFnCtxPassedInGetAuth } from '../utils/errors';
+import { clerkMiddlewareNotConfigured } from '../utils/errors';
 
-export const getAuth: GetAuthFn<Request, true> = (async (request: Request, opts?: AuthOptions) => {
-  if (!request) {
-    return errorThrower.throw(noFetchFnCtxPassedInGetAuth);
-  }
-
-  const authObjectFn = getContext('auth');
+export const getAuth: GetAuthFnNoRequest<SessionAuthObject, true> = (async (opts?: AuthOptions) => {
+  // @ts-expect-error: Untyped internal Clerk start context
+  const authObjectFn = getGlobalStartContext().auth;
 
   if (!authObjectFn) {
-    return errorThrower.throw(clerkHandlerNotConfigured);
+    return errorThrower.throw(clerkMiddlewareNotConfigured);
   }
 
-  // We're keeping it a promise for now to minimize breaking changes
+  // We're keeping it a promise for now for future changes
   const authObject = await Promise.resolve(authObjectFn({ treatPendingAsSignedOut: opts?.treatPendingAsSignedOut }));
 
   return getAuthObjectForAcceptedToken({ authObject, acceptsToken: opts?.acceptsToken });
-}) as GetAuthFn<Request, true>;
+}) as GetAuthFnNoRequest<SessionAuthObject, true>;
diff --git a/packages/tanstack-react-start/src/server/index.ts b/packages/tanstack-react-start/src/server/index.ts
@@ -1,7 +1,6 @@
-export * from './middlewareHandler';
-
 export * from './getAuth';
 export { clerkClient } from './clerkClient';
+export { clerkMiddleware } from './clerkMiddleware';
 
 /**
  * Re-export resource types from @clerk/backend