useNavigate() with absolute paths strips basepath during navigation in v1.121.21 #4471
Description
Which project does this relate to?
Router
Describe the bug
When using useNavigate() with absolute paths in components, the router basepath is stripped from the URL during navigation, particularly when URL parameters are involved. This breaks routing for applications deployed with a basepath (e.g., /streaming).
The issue appears to be similar to #2046, #1779, and #3436, but specifically affects useNavigate() usage with absolute paths.
// router.ts
import { queryClient } from '@providers/QueryProvider/QueryProvider.util.ts';
import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen.ts';
export const router = createRouter({
routeTree,
basepath: import.meta.env.PROD ? '/streaming' : import.meta.env.BASE_URL,
defaultPreload: 'intent',
scrollRestoration: true,
defaultStructuralSharing: true,
context: {
auth: undefined!,
queryClient: queryClient,
},
});
// Component using useNavigate
import { useNavigate } from '@tanstack/react-router';
export const GenericFolder = ({ type }) => {
const navigate = useNavigate();
const onClick = () => {
navigate({
to: `/saved/folder/generic/${type}`, // Absolute path
});
};
return <div onClick={onClick}>Navigate</div>;
};Your Example Website or App
Steps to Reproduce the Bug or Issue
- Set up TanStack Router with a basepath (e.g.,
basepath: '/streaming') - Deploy application so it runs at
https://example.com/streaming - Create a component that uses
useNavigate()with absolute paths (like/saved/folder/generic/${type}) - Navigate to a page that renders this component (e.g., https://example.com/streaming/dashboard)
- Trigger the navigation that adds URL parameters or changes the route
- Observe that the URL becomes
https://example.com/saved/folder/generic/sometypeinstead ofhttps://example.com/streaming/saved/folder/generic/sometype
Expected behavior
When using absolute paths with useNavigate(), the basepath should be preserved in the final URL. The navigation should result in https://example.com/streaming/saved/folder/generic/sometype.
Actual behavior
The basepath (/streaming) is stripped from the URL, resulting in https://example.com/saved/folder/generic/sometype, which breaks the application routing and leads to a 404 or "not found" page.
Additional context
Environment
- TanStack Router version: 1.121.21
- Framework: React 19.1.0
- Build tool: Vite 6.3.5
- Deployment: Production environment with basepath
Package.json dependencies
{
"@tanstack/react-router": "1.121.21",
"@tanstack/react-router-devtools": "1.121.21",
"@tanstack/router-plugin": "1.121.22",
"@tanstack/zod-adapter": "1.121.21"
}Version Information
Working version: 1.120.20 (but has build errors due to generator export changes)
Broken version: 1.121.21+ (navigation works but basepath is stripped)
Root Cause Analysis
Based on the TanStack Router documentation: "If a from route path isn't provided the router will assume you are navigating from the root / route and only auto-complete absolute paths".
This suggests that useNavigate() without a from property bypasses basepath handling when using absolute paths, while router.navigate() properly maintains the router context.
Impact on Developer Experience
This issue particularly affects:
- Reusable components that need to navigate but can't specify a from property (since they don't know where they'll be rendered)
- Monorepo/microfrontend architectures where components are shared across different applications
- Dynamic routing where the navigation target is computed at runtime
Related Issues
- Basepaths like "base%2Fpath" work properly in version 1.43.4 but not in 1.45.11 #2046: Basepaths being decoded during navigation
basepathbreaks routing in case its being found later within path #1779: Basepath breaks routing when found within path- Relative routing issue #3436: Relative routing issue with useNavigate()