useNavigate() with absolute paths strips basepath during navigation in v1.121.21

[cristianghita24]

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

https://stackblitz.com/github/tanstack/router/tree/main/examples/react/quickstart-file-based?file=src%2Fmain.tsx

Steps to Reproduce the Bug or Issue

1. Set up TanStack Router with a basepath (e.g., basepath: '/streaming')
2. Deploy application so it runs at https://example.com/streaming
3. Create a component that uses useNavigate() with absolute paths (like /saved/folder/generic/${type})
4. Navigate to a page that renders this component (e.g., https://example.com/streaming/dashboard)
5. Trigger the navigation that adds URL parameters or changes the route
6. Observe that the URL becomes https://example.com/saved/folder/generic/sometype instead of https://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:

1. Reusable components that need to navigate but can't specify a from property (since they don't know where they'll be rendered)
2. Monorepo/microfrontend architectures where components are shared across different applications
3. Dynamic routing where the navigation target is computed at runtime

Related Issues

• #2046: Basepaths being decoded during navigation
• #1779: Basepath breaks routing when found within path
• #3436: Relative routing issue with useNavigate()

[jvllmr]

Probably also related to #4401

[schiller-manuel]

can you please share a complete reproducer by forking the stackblitz example and applying the necessary changes? i wasn't able to reproduce here: https://stackblitz.com/edit/github-p9sh7zjw?file=src%2Fmain.tsx,src%2Froutes%2Fabout.tsx,src%2Froutes%2Findex.tsx

[cristianghita24]

@schiller-manuel I don't think/know if it is reproduceable via stackblitz. I encountered this bug after deploying my react SPA and setting a url_base in my router (in my case it was /streaming). On v1.120.20 it worked fine - e.g.: going from [host]/streaming/dashboard to [host]/streaming/saved/ would work fine, but on v1.121.21 it would remove /streaming or even the route from the url.

I used AI to investigate the bug and even generate the issue as I am not so experienced with tanstack-router codebase. I hope I gave enough information to help you start the investigation, let me know if I can provide anything else please.

[SeanCassiere]

In the absence of a proper reproducible sandbox, I'm taking the changes in #4472 as the fix for this issue.

The fix for this should be available in this release - https://github.com/TanStack/router/releases/tag/v1.121.33

@cristianghita24 please try out this release in your project to confirm. If it does not fix your problem, please open a new issue with a reproducible sandbox. Without a reproducible sandbox, we really are unable to figure out what specific scenarios are causing the issues you are facing.

[cristianghita24]

@SeanCassiere upgraded to v1.121.34 and the issue is fixed, many thanks