fix: navigate() with href containing basepath (#6335)

jakst · schiller-manuel · web-flow · commit a1324bb155ae · 2026-01-08T23:33:41.000+01:00
Co-authored-by: Manuel Schiller &lt;manuel.schiller@caligano.de&gt;
diff --git a/e2e/react-router/basepath-file-based/src/routes/index.tsx b/e2e/react-router/basepath-file-based/src/routes/index.tsx
@@ -39,6 +39,27 @@ function App() {
         }
       >
         Navigate to /redirectReload
+      </button>{' '}
+      <button
+        data-testid="to-about-href-with-basepath-btn"
+        onClick={() =>
+          navigate({
+            href: '/app/about',
+          })
+        }
+      >
+        Navigate to /about using href with basepath
+      </button>{' '}
+      <button
+        data-testid="to-about-href-with-basepath-reload-btn"
+        onClick={() =>
+          navigate({
+            href: '/app/about',
+            reloadDocument: true,
+          })
+        }
+      >
+        Navigate to /about using href with basepath (reloadDocument)
       </button>
     </div>
   )
diff --git a/e2e/react-router/basepath-file-based/tests/reload-document.test.ts b/e2e/react-router/basepath-file-based/tests/reload-document.test.ts
@@ -38,3 +38,27 @@ test('redirect respects basepath with reloadDocument = true on redirect', async
   await page.waitForURL('/app/about')
   await expect(page.getByTestId(`about-component`)).toBeInViewport()
 })
+
+test('navigate() with href containing basepath', async ({ page }) => {
+  await page.goto(`/app/`)
+  await expect(page.getByTestId(`home-component`)).toBeInViewport()
+
+  const aboutBtn = page.getByTestId(`to-about-href-with-basepath-btn`)
+  await aboutBtn.click()
+  // Should navigate to /app/about, NOT /app/app/about
+  await page.waitForURL('/app/about')
+  await expect(page.getByTestId(`about-component`)).toBeInViewport()
+})
+
+test('navigate() with href containing basepath and reloadDocument=true', async ({
+  page,
+}) => {
+  await page.goto(`/app/`)
+  await expect(page.getByTestId(`home-component`)).toBeInViewport()
+
+  const aboutBtn = page.getByTestId(`to-about-href-with-basepath-reload-btn`)
+  await aboutBtn.click()
+  // Should navigate to /app/about, NOT stay on current page
+  await page.waitForURL('/app/about')
+  await expect(page.getByTestId(`about-component`)).toBeInViewport()
+})
diff --git a/e2e/react-start/custom-basepath/src/routeTree.gen.ts b/e2e/react-start/custom-basepath/src/routeTree.gen.ts
@@ -11,6 +11,7 @@
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as UsersRouteImport } from './routes/users'
 import { Route as PostsRouteImport } from './routes/posts'
+import { Route as NavigateTestRouteImport } from './routes/navigate-test'
 import { Route as LogoutRouteImport } from './routes/logout'
 import { Route as DeferredRouteImport } from './routes/deferred'
 import { Route as IndexRouteImport } from './routes/index'
@@ -34,6 +35,11 @@ const PostsRoute = PostsRouteImport.update({
   path: '/posts',
   getParentRoute: () => rootRouteImport,
 } as any)
+const NavigateTestRoute = NavigateTestRouteImport.update({
+  id: '/navigate-test',
+  path: '/navigate-test',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const LogoutRoute = LogoutRouteImport.update({
   id: '/logout',
   path: '/logout',
@@ -99,6 +105,7 @@ export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
   '/deferred': typeof DeferredRoute
   '/logout': typeof LogoutRoute
+  '/navigate-test': typeof NavigateTestRoute
   '/posts': typeof PostsRouteWithChildren
   '/users': typeof UsersRouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
@@ -115,6 +122,7 @@ export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/deferred': typeof DeferredRoute
   '/logout': typeof LogoutRoute
+  '/navigate-test': typeof NavigateTestRoute
   '/api/users': typeof ApiUsersRouteWithChildren
   '/posts/$postId': typeof PostsPostIdRoute
   '/redirect/throw-it': typeof RedirectThrowItRoute
@@ -130,6 +138,7 @@ export interface FileRoutesById {
   '/': typeof IndexRoute
   '/deferred': typeof DeferredRoute
   '/logout': typeof LogoutRoute
+  '/navigate-test': typeof NavigateTestRoute
   '/posts': typeof PostsRouteWithChildren
   '/users': typeof UsersRouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
@@ -148,6 +157,7 @@ export interface FileRouteTypes {
     | '/'
     | '/deferred'
     | '/logout'
+    | '/navigate-test'
     | '/posts'
     | '/users'
     | '/api/users'
@@ -164,6 +174,7 @@ export interface FileRouteTypes {
     | '/'
     | '/deferred'
     | '/logout'
+    | '/navigate-test'
     | '/api/users'
     | '/posts/$postId'
     | '/redirect/throw-it'
@@ -178,6 +189,7 @@ export interface FileRouteTypes {
     | '/'
     | '/deferred'
     | '/logout'
+    | '/navigate-test'
     | '/posts'
     | '/users'
     | '/api/users'
@@ -195,6 +207,7 @@ export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
   DeferredRoute: typeof DeferredRoute
   LogoutRoute: typeof LogoutRoute
+  NavigateTestRoute: typeof NavigateTestRoute
   PostsRoute: typeof PostsRouteWithChildren
   UsersRoute: typeof UsersRouteWithChildren
   ApiUsersRoute: typeof ApiUsersRouteWithChildren
@@ -219,6 +232,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof PostsRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/navigate-test': {
+      id: '/navigate-test'
+      path: '/navigate-test'
+      fullPath: '/navigate-test'
+      preLoaderRoute: typeof NavigateTestRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/logout': {
       id: '/logout'
       path: '/logout'
@@ -346,6 +366,7 @@ const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
   DeferredRoute: DeferredRoute,
   LogoutRoute: LogoutRoute,
+  NavigateTestRoute: NavigateTestRoute,
   PostsRoute: PostsRouteWithChildren,
   UsersRoute: UsersRouteWithChildren,
   ApiUsersRoute: ApiUsersRouteWithChildren,
diff --git a/e2e/react-start/custom-basepath/src/routes/navigate-test.tsx b/e2e/react-start/custom-basepath/src/routes/navigate-test.tsx
@@ -0,0 +1,36 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/navigate-test')({
+  component: NavigateTest,
+})
+
+function NavigateTest() {
+  const navigate = Route.useNavigate()
+
+  return (
+    <div className="p-2">
+      <h3 data-testid="navigate-test-component">Navigate Test</h3>
+      <button
+        data-testid="to-posts-href-with-basepath-btn"
+        onClick={() =>
+          navigate({
+            href: '/custom/basepath/posts',
+          })
+        }
+      >
+        Navigate to /posts using href with basepath
+      </button>{' '}
+      <button
+        data-testid="to-posts-href-with-basepath-reload-btn"
+        onClick={() =>
+          navigate({
+            href: '/custom/basepath/posts',
+            reloadDocument: true,
+          })
+        }
+      >
+        Navigate to /posts using href with basepath (reloadDocument)
+      </button>
+    </div>
+  )
+}
diff --git a/e2e/react-start/custom-basepath/src/routes/posts.tsx b/e2e/react-start/custom-basepath/src/routes/posts.tsx
@@ -18,7 +18,7 @@ function PostsComponent() {
   const posts = Route.useLoaderData()
 
   return (
-    <div className="p-2 flex gap-2">
+    <div className="p-2 flex gap-2" data-testid="posts-component">
       <ul className="list-disc pl-4">
         {[...posts, { id: 'i-do-not-exist', title: 'Non-existent Post' }].map(
           (post) => {
diff --git a/e2e/react-start/custom-basepath/tests/navigation.spec.ts b/e2e/react-start/custom-basepath/tests/navigation.spec.ts
@@ -75,3 +75,28 @@ test('server-side redirect', async ({ page, baseURL }) => {
       expect(headers.get('location')).toBe('/custom/basepath/posts/1')
     })
 })
+
+test('navigate() with href containing basepath', async ({ page, baseURL }) => {
+  await page.goto('/navigate-test')
+  await expect(page.getByTestId('navigate-test-component')).toBeVisible()
+
+  const btn = page.getByTestId('to-posts-href-with-basepath-btn')
+  await btn.click()
+  // Should navigate to /custom/basepath/posts, NOT /custom/basepath/custom/basepath/posts
+  await page.waitForURL(`${baseURL}/posts`)
+  await expect(page.getByTestId('posts-component')).toBeVisible()
+})
+
+test('navigate() with href containing basepath and reloadDocument=true', async ({
+  page,
+  baseURL,
+}) => {
+  await page.goto('/navigate-test')
+  await expect(page.getByTestId('navigate-test-component')).toBeVisible()
+
+  const btn = page.getByTestId('to-posts-href-with-basepath-reload-btn')
+  await btn.click()
+  // Should navigate to /custom/basepath/posts, NOT stay on current page
+  await page.waitForURL(`${baseURL}/posts`)
+  await expect(page.getByTestId('posts-component')).toBeVisible()
+})
diff --git a/e2e/solid-router/basepath-file-based/src/routes/index.tsx b/e2e/solid-router/basepath-file-based/src/routes/index.tsx
@@ -19,6 +19,27 @@ function App() {
         }
       >
         Navigate to /about with document reload
+      </button>{' '}
+      <button
+        data-testid="to-about-href-with-basepath-btn"
+        onClick={() =>
+          navigate({
+            href: '/app/about',
+          })
+        }
+      >
+        Navigate to /about using href with basepath
+      </button>{' '}
+      <button
+        data-testid="to-about-href-with-basepath-reload-btn"
+        onClick={() =>
+          navigate({
+            href: '/app/about',
+            reloadDocument: true,
+          })
+        }
+      >
+        Navigate to /about using href with basepath (reloadDocument)
       </button>
     </div>
   )
diff --git a/e2e/solid-router/basepath-file-based/tests/reload-document.test.ts b/e2e/solid-router/basepath-file-based/tests/reload-document.test.ts
@@ -16,3 +16,27 @@ test('navigate() respects basepath for when reloadDocument=true', async ({
   await page.waitForURL('/app/')
   await expect(page.getByTestId(`home-component`)).toBeInViewport()
 })
+
+test('navigate() with href containing basepath', async ({ page }) => {
+  await page.goto(`/app/`)
+  await expect(page.getByTestId(`home-component`)).toBeInViewport()
+
+  const aboutBtn = page.getByTestId(`to-about-href-with-basepath-btn`)
+  await aboutBtn.click()
+  // Should navigate to /app/about, NOT /app/app/about
+  await page.waitForURL('/app/about')
+  await expect(page.getByTestId(`about-component`)).toBeInViewport()
+})
+
+test('navigate() with href containing basepath and reloadDocument=true', async ({
+  page,
+}) => {
+  await page.goto(`/app/`)
+  await expect(page.getByTestId(`home-component`)).toBeInViewport()
+
+  const aboutBtn = page.getByTestId(`to-about-href-with-basepath-reload-btn`)
+  await aboutBtn.click()
+  // Should navigate to /app/about, NOT stay on current page
+  await page.waitForURL('/app/about')
+  await expect(page.getByTestId(`about-component`)).toBeInViewport()
+})
diff --git a/e2e/solid-start/custom-basepath/src/routeTree.gen.ts b/e2e/solid-start/custom-basepath/src/routeTree.gen.ts
@@ -11,6 +11,7 @@
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as UsersRouteImport } from './routes/users'
 import { Route as PostsRouteImport } from './routes/posts'
+import { Route as NavigateTestRouteImport } from './routes/navigate-test'
 import { Route as LogoutRouteImport } from './routes/logout'
 import { Route as DeferredRouteImport } from './routes/deferred'
 import { Route as IndexRouteImport } from './routes/index'
@@ -34,6 +35,11 @@ const PostsRoute = PostsRouteImport.update({
   path: '/posts',
   getParentRoute: () => rootRouteImport,
 } as any)
+const NavigateTestRoute = NavigateTestRouteImport.update({
+  id: '/navigate-test',
+  path: '/navigate-test',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const LogoutRoute = LogoutRouteImport.update({
   id: '/logout',
   path: '/logout',
@@ -99,6 +105,7 @@ export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
   '/deferred': typeof DeferredRoute
   '/logout': typeof LogoutRoute
+  '/navigate-test': typeof NavigateTestRoute
   '/posts': typeof PostsRouteWithChildren
   '/users': typeof UsersRouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
@@ -115,6 +122,7 @@ export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/deferred': typeof DeferredRoute
   '/logout': typeof LogoutRoute
+  '/navigate-test': typeof NavigateTestRoute
   '/api/users': typeof ApiUsersRouteWithChildren
   '/posts/$postId': typeof PostsPostIdRoute
   '/redirect/throw-it': typeof RedirectThrowItRoute
@@ -130,6 +138,7 @@ export interface FileRoutesById {
   '/': typeof IndexRoute
   '/deferred': typeof DeferredRoute
   '/logout': typeof LogoutRoute
+  '/navigate-test': typeof NavigateTestRoute
   '/posts': typeof PostsRouteWithChildren
   '/users': typeof UsersRouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
@@ -148,6 +157,7 @@ export interface FileRouteTypes {
     | '/'
     | '/deferred'
     | '/logout'
+    | '/navigate-test'
     | '/posts'
     | '/users'
     | '/api/users'
@@ -164,6 +174,7 @@ export interface FileRouteTypes {
     | '/'
     | '/deferred'
     | '/logout'
+    | '/navigate-test'
     | '/api/users'
     | '/posts/$postId'
     | '/redirect/throw-it'
@@ -178,6 +189,7 @@ export interface FileRouteTypes {
     | '/'
     | '/deferred'
     | '/logout'
+    | '/navigate-test'
     | '/posts'
     | '/users'
     | '/api/users'
@@ -195,6 +207,7 @@ export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
   DeferredRoute: typeof DeferredRoute
   LogoutRoute: typeof LogoutRoute
+  NavigateTestRoute: typeof NavigateTestRoute
   PostsRoute: typeof PostsRouteWithChildren
   UsersRoute: typeof UsersRouteWithChildren
   ApiUsersRoute: typeof ApiUsersRouteWithChildren
@@ -219,6 +232,13 @@ declare module '@tanstack/solid-router' {
       preLoaderRoute: typeof PostsRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/navigate-test': {
+      id: '/navigate-test'
+      path: '/navigate-test'
+      fullPath: '/navigate-test'
+      preLoaderRoute: typeof NavigateTestRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/logout': {
       id: '/logout'
       path: '/logout'
@@ -346,6 +366,7 @@ const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
   DeferredRoute: DeferredRoute,
   LogoutRoute: LogoutRoute,
+  NavigateTestRoute: NavigateTestRoute,
   PostsRoute: PostsRouteWithChildren,
   UsersRoute: UsersRouteWithChildren,
   ApiUsersRoute: ApiUsersRouteWithChildren,
diff --git a/e2e/solid-start/custom-basepath/src/routes/navigate-test.tsx b/e2e/solid-start/custom-basepath/src/routes/navigate-test.tsx
diff --git a/e2e/solid-start/custom-basepath/src/routes/posts.tsx b/e2e/solid-start/custom-basepath/src/routes/posts.tsx
diff --git a/e2e/solid-start/custom-basepath/tests/navigation.spec.ts b/e2e/solid-start/custom-basepath/tests/navigation.spec.ts
diff --git a/packages/router-core/src/router.ts b/packages/router-core/src/router.ts
