fix(tanstack-react-start): Parse URL query params for TanStack Router navigation

.changeset/fix-tanstack-navigation-query-params.md

@@ -0,0 +1,5 @@
+---
+'@clerk/tanstack-react-start': patch
+---
+
+Fix navigation with query parameters in TanStack Start apps. Previously, URLs with query parameters (e.g., `/sign-in?redirect_url=...`) would cause "Not Found" errors because TanStack Router doesn't parse query strings from the `to` parameter. The fix properly separates pathname, search params, and hash when calling TanStack Router's navigate function.

packages/react-router/src/client/usePathnameWithoutSplatRouteParams.tsx

@@ -1,3 +1,4 @@
+import { useRef } from 'react';
 import { useLocation, useParams } from 'react-router';
 
 export const usePathnameWithoutSplatRouteParams = () => {
@@ -14,5 +15,13 @@ export const usePathnameWithoutSplatRouteParams = () => {
   // eg /user/123/profile/security will return /user/123/profile as the path
   const path = pathname.replace(splatRouteParam, '').replace(/\/$/, '').replace(/^\//, '').trim();
 
-  return `/${path}`;
+  const computedPath = `/${path}`;
+
+  // Stabilize the base path to prevent race conditions during navigation away.
+  // When the router navigates to a different route, useLocation() returns the
+  // new pathname before this component unmounts. This causes the basePath to change,
+  // which makes the SignIn/SignUp catch-all route fire RedirectToSignIn incorrectly.
+  // Matches the pattern used in @clerk/nextjs usePathnameWithoutCatchAll.
+  const stablePath = useRef(computedPath);
+  return stablePath.current;
 };

packages/tanstack-react-start/src/__tests__/parseUrlForNavigation.test.ts

@@ -0,0 +1,113 @@
+import { parseUrlForNavigation } from '../client/utils';
+
+const BASE_URL = 'https://example.com';
+
+describe('parseUrlForNavigation', () => {
+  it('parses pathname only', () => {
+    const result = parseUrlForNavigation('/sign-in', BASE_URL);
+    expect(result).toEqual({
+      to: '/sign-in',
+      search: undefined,
+      hash: undefined,
+    });
+  });
+
+  it('parses pathname with query parameters', () => {
+    const result = parseUrlForNavigation('/sign-in?redirect_url=https://example.com', BASE_URL);
+    expect(result).toEqual({
+      to: '/sign-in',
+      search: { redirect_url: 'https://example.com' },
+      hash: undefined,
+    });
+  });
+
+  it('parses pathname with multiple query parameters', () => {
+    const result = parseUrlForNavigation('/sign-in?redirect_url=https://example.com&foo=bar', BASE_URL);
+    expect(result).toEqual({
+      to: '/sign-in',
+      search: { redirect_url: 'https://example.com', foo: 'bar' },
+      hash: undefined,
+    });
+  });
+
+  it('parses pathname with hash', () => {
+    const result = parseUrlForNavigation('/sign-in#section', BASE_URL);
+    expect(result).toEqual({
+      to: '/sign-in',
+      search: undefined,
+      hash: 'section',
+    });
+  });
+
+  it('parses pathname with query parameters and hash', () => {
+    const result = parseUrlForNavigation('/sign-in?redirect_url=https://example.com#section', BASE_URL);
+    expect(result).toEqual({
+      to: '/sign-in',
+      search: { redirect_url: 'https://example.com' },
+      hash: 'section',
+    });
+  });
+
+  it('handles encoded query parameters', () => {
+    const result = parseUrlForNavigation('/sign-in?redirect_url=https%3A%2F%2Fexample.com%2Fpath', BASE_URL);
+    expect(result).toEqual({
+      to: '/sign-in',
+      search: { redirect_url: 'https://example.com/path' },
+      hash: undefined,
+    });
+  });
+
+  it('handles root path', () => {
+    const result = parseUrlForNavigation('/', BASE_URL);
+    expect(result).toEqual({
+      to: '/',
+      search: undefined,
+      hash: undefined,
+    });
+  });
+
+  it('handles nested paths', () => {
+    const result = parseUrlForNavigation('/auth/sign-in?foo=bar', BASE_URL);
+    expect(result).toEqual({
+      to: '/auth/sign-in',
+      search: { foo: 'bar' },
+      hash: undefined,
+    });
+  });
+
+  it('handles empty hash', () => {
+    const result = parseUrlForNavigation('/sign-in#', BASE_URL);
+    expect(result).toEqual({
+      to: '/sign-in',
+      search: undefined,
+      hash: undefined,
+    });
+  });
+
+  it('handles complex satellite redirect URL', () => {
+    const result = parseUrlForNavigation(
+      '/sign-in?redirect_url=https%3A%2F%2Fsatellite.example.com%2Fdashboard&sign_in_force_redirect_url=https%3A%2F%2Fmain.example.com',
+      BASE_URL,
+    );
+    expect(result).toEqual({
+      to: '/sign-in',
+      search: {
+        redirect_url: 'https://satellite.example.com/dashboard',
+        sign_in_force_redirect_url: 'https://main.example.com',
+      },
+      hash: undefined,
+    });
+  });
+
+  it('handles hash that looks like a path with query params (PathRouter format)', () => {
+    // This is what PathRouter converts from: /sign-in#/?redirect_url=...
+    // After mergeFragmentIntoUrl, it becomes: /sign-in?redirect_url=...
+    // We should correctly handle both formats
+    const result = parseUrlForNavigation('/sign-in?redirect_url=https://satellite.com', BASE_URL);
+    expect(result).toEqual({
+      to: '/sign-in',
+      search: { redirect_url: 'https://satellite.com' },
+      hash: undefined,
+    });
+  });
+});

packages/tanstack-react-start/src/client/ClerkProvider.tsx

@@ -8,7 +8,7 @@ import { isClient } from '../utils';
 import { ClerkOptionsProvider } from './OptionsContext';
 import type { TanstackStartClerkProviderProps } from './types';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
-import { mergeWithPublicEnvs, pickFromClerkInitState } from './utils';
+import { mergeWithPublicEnvs, parseUrlForNavigation, pickFromClerkInitState } from './utils';
 
 export * from '@clerk/react';
 
@@ -57,18 +57,24 @@ export function ClerkProvider<TUi extends Ui = Ui>({
         <ReactClerkProvider
           initialState={clerkSsrState}
           sdkMetadata={SDK_METADATA}
-          routerPush={(to: string) =>
-            awaitableNavigateRef.current?.({
-              to,
+          routerPush={(to: string) => {
+            const { search, hash, ...rest } = parseUrlForNavigation(to, window.location.origin);
+            return awaitableNavigateRef.current?.({
+              ...rest,
+              search: search as any,
+              hash,
               replace: false,
-            })
-          }
-          routerReplace={(to: string) =>
-            awaitableNavigateRef.current?.({
-              to,
+            });
+          }}
+          routerReplace={(to: string) => {
+            const { search, hash, ...rest } = parseUrlForNavigation(to, window.location.origin);
+            return awaitableNavigateRef.current?.({
+              ...rest,
+              search: search as any,
+              hash,
               replace: true,
-            })
-          }
+            });
+          }}
           {...mergedProps}
           {...keylessProps}
         >

packages/tanstack-react-start/src/client/uiComponents.tsx

@@ -8,6 +8,7 @@ import {
 import { useRoutingProps } from '@clerk/react/internal';
 import type { OrganizationProfileProps, SignInProps, SignUpProps, UserProfileProps } from '@clerk/shared/types';
 import { useLocation, useParams } from '@tanstack/react-router';
+import { useRef } from 'react';
 
 const usePathnameWithoutSplatRouteParams = () => {
   const { _splat } = useParams({
@@ -24,7 +25,15 @@ const usePathnameWithoutSplatRouteParams = () => {
   // eg /user/123/profile/security will return /user/123/profile as the path
   const path = pathname.replace(splatRouteParam, '').replace(/\/$/, '').replace(/^\//, '').trim();
 
-  return `/${path}`;
+  const computedPath = `/${path}`;
+
+  // Stabilize the base path to prevent race conditions during navigation away.
+  // When TanStack Router navigates to a different route, useLocation() returns the
+  // new pathname before this component unmounts. This causes the basePath to change,
+  // which makes the SignIn/SignUp catch-all route fire RedirectToSignIn incorrectly.
+  // Matches the pattern used in @clerk/nextjs usePathnameWithoutCatchAll.
+  const stablePath = useRef(computedPath);
+  return stablePath.current;
 };
 
 // The assignment of UserProfile with BaseUserProfile props is used

packages/tanstack-react-start/src/client/utils.ts

@@ -76,3 +76,24 @@ export const mergeWithPublicEnvs = (restInitState: any) => {
     prefetchUI: restInitState.prefetchUI ?? envVars.prefetchUI,
   };
 };
+
+export type ParsedNavigationUrl = {
+  to: string;
+  search?: Record<string, string>;
+  hash?: string;
+};
+
+/**
+ * Parses a URL string into TanStack Router navigation options.
+ * TanStack Router doesn't parse query strings from the `to` parameter,
+ * so we need to extract pathname, search params, and hash separately.
+ */
+export function parseUrlForNavigation(to: string, baseUrl: string): ParsedNavigationUrl {
+  const url = new URL(to, baseUrl);
+  const searchParams = Object.fromEntries(url.searchParams);
+  return {
+    to: url.pathname,
+    search: Object.keys(searchParams).length > 0 ? searchParams : undefined,
+    hash: url.hash ? url.hash.slice(1) : undefined,
+  };
+}