Best way to preserve "global" search params when switching routes

[nilshartmann]

Hi,

I have some search params that have a global-ish meaning (imagine something like a theme setting or a session id). Is there a way to (automatically) add this params to all links that are rendered in my app? Or at least on links that point to a specific subtree in my route tree?

Thanks,
Nils

[ashishsurya]

I think we can do that using zod library, by defining the default values and using zod's parse function for parsing the seach params passed at the run time

Not sure if this works in production, or not sure of any tradeoffs.

const rootSearchParams = z.object({
  start: z.string().default(""),
  timeFrame: z.string().default("Last 15 Minutes"),
});

export const Route = createRootRoute({
  component: () => (
    <>
      <span>
        <Link to={"/"}>To Index</Link>
        <Link to={"/about"}>
          To About
        </Link>
      </span>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
  onEnter: () => console.log("ROOT ROUTE"),
  validateSearch: rootSearchParams,
});

[nilshartmann]

Hi @ashishsurya ,

I tried your approach, but the search params are not added to any url when using the Link component without explicitly settings them.

[ashishsurya]

Yeah you want to pass search params if they are configured

[nilshartmann]

It would be nice if it would be possible to mark search params as "global" so that they are automatically added when the Link components renders an a element (and everywhere else a URL is generated by TS Router).

I think this would align the search params even more with the idea that search params a replacement for global state. Using global state I also don't have to add props for any new component I render.

[michaeltnguyen]

This is now supported via retainSearchParams middleware.

https://tanstack.com/router/latest/docs/framework/react/api/router/retainSearchParamsFunction

[devinrhode2]

Can we think about adding some docs on best practices around retainSearchParams?

TanStack is incredibly flexible and supports many use cases. In our app, we have something that could be thought of as a "tenant ID" or "project id" these projects are approximately 9-12 months for our users to complete. Any data they see, and any action they take on that data, will be tied to that tenant id. So, I presume our best url structure is like:
/ui-section-name/tenant/$tenantId/view-something

One tradeoff I had forgotten to take into account (in my earlier discussions with my team), is the fact that paths/path segments are routes which can have their own data loader/preload/beforeLoad associated with them. We can then use getRouteApi('/ui-section-name/tenant-list').useLoaderData() to get tenant metadata from any of these route loaders in other parts of the app.

So, maybe there should be a documentation page on when to use path params, optional path params, query params, or not put state in url altogether. When should we use retainSearchParams vs making something a path params. This will help teams newer to tanstack router design and layout their url schemes in a way that won't change much over time. Redirects are easy in tanstack, but can be hard to maintain over time. Also, merge conflicts on files getting added and removed are difficult too.

@TkDodo - any chance you could help here, maybe you have a blog post I should read?

[devinrhode2]

@TkDodo if there's nothing out there already, I could draft a docs page on this