feat(tanstack-react-start): Introduce middleware and support for TanStack Start RC

.changeset/spotty-cooks-march.md

@@ -0,0 +1,5 @@
+---
+"@clerk/tanstack-react-start": minor
+---
+
+placeholder trigger test

.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',

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"

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

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

@@ -1,13 +1,10 @@
 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';
+import { getRequest } 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(getRequest());
 
   return {
     userId,

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()],
+  };
+});

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"
   },

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",
 ]
 `;

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}

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

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

@@ -1,22 +1,18 @@
-import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
+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, noFetchFnCtxPassedInGetAuth } 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<{}, 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 });

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

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

@@ -8,7 +8,7 @@ import type {
   SignUpForceRedirectUrl,
 } from '@clerk/types';
 
-export type LoaderOptions = {
+export type ClerkMiddlewareOptions = {
   publishableKey?: string;
   jwtKey?: string;
   secretKey?: string;
@@ -23,6 +23,8 @@ export type LoaderOptions = {
   SignUpFallbackRedirectUrl &
   LegacyRedirectProps;
 
+export type LoaderOptions = ClerkMiddlewareOptions;
+
 export type AdditionalStateOptions = SignInFallbackRedirectUrl &
   SignUpFallbackRedirectUrl &
   SignInForceRedirectUrl &

packages/tanstack-react-start/src/server/utils/index.ts

@@ -48,10 +48,7 @@ export function getResponseClerkState(requestState: RequestState, additionalStat
       additionalStateOptions.signUpFallbackRedirectUrl || getEnvVariable('CLERK_SIGN_UP_FALLBACK_REDIRECT_URL') || '',
   });
 
-  return {
-    clerkInitialState,
-    headers: requestState.headers,
-  };
+  return clerkInitialState;
 }
 
 /**