useQueryState causes a navigation to trailing slash with search param w/ TanStack Router

[mirshko]

Context

What's your version of nuqs?

  "name": "nuqs-bug",
    "nuqs": "^2.7.3",

What framework are you using?

TanStack Router

Which version of your framework are you using?

    "@tanstack/react-devtools": "^0.7.0",
    "@tanstack/react-router": "^1.132.0",
    "@tanstack/react-router-devtools": "^1.132.0",
    "@tanstack/router-plugin": "^1.132.0",

Description

When using useQueryState (or others) and calling the set(param) function, it causes a navigation, appending a trailing slash to the current route.

Expected behavior is that it doesn't cause a route transition with the path and only updates the query parameters.

Reproduction

https://codesandbox.io/p/github/mirshko/nuqs-bug/main?import=true

you can test it easier on the the second page, click "To Second Page Test" in preview window.

[franky47]

Yes I had noticed this, it looks like it comes from going through the to argument of useNavigate to support nuqs' custom serialisation, it doesn't occur if we pass "hydrated" search params as the search argument.

Considering TSR does its own thing in terms of (de)serialisation, maybe we should drop this idea of "pretty URLs" in there (which would be causing issues anyway with custom (de)serialisation layers). It shouldn't break existing URLs (as browsers & servers are smart enough to decode when building URL objects), but it will then serialise to all url-encoded characters (which TSR seems to be ok with).

[andreastande]

Noticed the same and been working on a reproduction for the past 1 hour, should have looked if someone already had created an issue on it...

Anyways, here's another reproduction if needed (a bit more styled lol): https://codesandbox.io/p/sandbox/github/andreastande/nuqs-tsr-adapter-trailing-slash-repro

[mirshko]

Yes I had noticed this, it looks like it comes from going through the to argument of useNavigate to support nuqs' custom serialisation, it doesn't occur if we pass "hydrated" search params as the search argument.

Considering TSR does its own thing in terms of (de)serialisation, maybe we should drop this idea of "pretty URLs" in there (which would be causing issues anyway with custom (de)serialisation layers). It shouldn't break existing URLs (as browsers & servers are smart enough to decode when building URL objects), but it will then serialise to all url-encoded characters (which TSR seems to be ok with).

I would agree here, it’s a little weird to go from having a pretty url to a non pretty url and vice versa, we’ve got some links that pre-populate the search params and then on the page they’re changed with nuqs, so then ofc the URLs change from encoded to non.

I’m in favor of this as a setting for sure.

On the useNavigate I wonder if it’s easier to just put the to: as ., unless it already is, to prevent the path change. Or perhaps find a way to merge in the from attribute in the useQueryState.

[franky47]

This is how it's implemented at the moment:

nuqs/packages/nuqs/src/adapters/tanstack-router.ts

Lines 50 to 68 in 82653f9

	navigate({
	// I know the docs say to use `search` here, but it would require
	// userland code to stitch the nuqs definitions to the route declarations
	// in order for TSR to serialize them, which kind of breaks the
	// "works out of the box" promise, and it also wouldn't support
	// the custom URL encoding.
	// TBC if it causes issues with consuming those search params
	// in other parts of the app.
	//
	// When we clear the search, passing an empty string causes
	// a type error and possible basepath issues, so we switch it to '.' instead.
	// See https://github.com/47ng/nuqs/pull/953#issuecomment-3003583471
	to: renderQueryString(search) || '.',
	// `from` will be handled by tanstack router match resolver, code snippet:
	// https://github.com/TanStack/router/blob/5d940e2d8bdb12e213eede0abe8012855433ec4b/packages/react-router/src/link.tsx#L108-L112
	...(from ? { from } : {}),
	replace: options.history === 'replace',
	resetScroll: options.scroll,
	hash: prevHash => prevHash ?? ''

The issue is that the updateUrl adapter function gets fed already serialised values, as they have gone through each parser's serialisation ahead of time. We might be able to force-feed those to the search property of navigate as strings, but I bet it expects values to conform to whatever type validateSearch returns.

Or perhaps find a way to merge in the from attribute in the useQueryState.

The from property is set from this piece of code, suggested by @SeanCassiere in #953 (comment) :

nuqs/packages/nuqs/src/adapters/tanstack-router.ts

Lines 15 to 20 in 82653f9

	const from = useMatches({
	select: matches =>
	matches.length > 0
	? (matches[matches.length - 1]?.fullPath as string)
	: undefined
	})

[andreastande]

How about just using a function to remove the trailing slash before passing it to the to argument of navigation?

An implementation like this should do the trick:

// /foo/?bar=baz -> /foo?bar=baz
function removeTrailingSlash(to: string): string {
  const [path, query] = to.split("?", 2)
  const normalizedPath = path.replace(/\/+$/, "") || "/"
  const normalizedTo = query ? `${normalizedPath}?${query}` : normalizedPath

  return normalizedTo
}

I have updated my reproduction, I highly recommend checking it out. It showcases how this function solves the problem, and includes a comprehensive test suite to ensure the logic is correct.

Perhaps the fix is as simple as just wrapping renderQueryString with this function? One can hope.

nuqs/packages/nuqs/src/adapters/tanstack-router.ts

Line 62 in 82653f9

to: renderQueryString(search) || '.',

Updated reproduction:

• CodeSandbox: https://codesandbox.io/p/sandbox/github/andreastande/nuqs-tsr-adapter-trailing-slash-repro
• GitHub: https://github.com/andreastande/nuqs-tsr-adapter-trailing-slash-repro

Edit: Experiencing different behavior between CodeSandbox and locally. Works fine locally, but not as expected in CodeSandbox. So I suggest cloning/forking the repo.

Edit 2: removeTrailingSlash wrongfully relied on History API, should only return a string.

[franky47]

This is actually how all the other adapters work, in the shallow: true mode (the shallow: false mode would usually use router APIs to notify the server for SSR).

I'll have a look at your repro, thanks! And yes, CodeSandbox doesn't update its internal URL UI, so it's not great for repros in that regard (apart from serving as a distribution platform).

[andreastande]

window.history.replaceState is not relevant at all for the function, was just some left-over code in my own repro that I forgot would not apply here. Instead, it should just return a string. Updated now.

And yeah, shallow routing is awesome!

[franky47]

I had a look at your implementation, it's not really solving the source of the problem but rather applying a fix after the fact, but I managed to get something working by passing the pathname + search in the to property of navigate, and set from: '/'. See #1217.

It might be a very wrong approach, and I'd need to dive deeper into how TSR works when navigating to see what this might impact (loaders, maybe?), but it does indeed not append the trailing slash.

Could y'all give it a try and see how it behaves please?

pnpm add https://pkg.pr.new/nuqs@1217

[andreastande]

Seems to functionally work fine from my small testing. But couldn't tell you if it affects loaders or other areas 🤷

[mirshko]

We don't use loaders in our site, but yeah this works.

I would be interested in disabling the prettyUrls feature you have to match the TSR params.

Is there an easy way to do this right now?

[franky47]

Is there an easy way to do this right now?

Unfortunately no, the renderQueryString function that's used to do the custom encoding isn't dependency injectable or configurable, I need to find a clean way to do this (especially as it's not only used in a React context, but also in the serializer which can be called from anywhere).

[mirshko]

Is there an easy way to do this right now?

Unfortunately no, the renderQueryString function that's used to do the custom encoding isn't dependency injectable or configurable, I need to find a clean way to do this (especially as it's not only used in a React context, but also in the serializer which can be called from anywhere).

Would it be possible to export this as a separate function to be able to pipe back into TSR's search serializers? https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization#using-base64 since you can use a custom serializer.