URL state "flickers" before settling in Next.js App Router

[aurorascharff]

Hello! I'm experiencing the state in the URL "flickering" before it settles. I'm using the Next.js App Router.

The URL params are being used to render a server component which retriggers on URL change. Pay attention to the URL after I click.

Oct-27-2024.14-06-13.mp4

// CategoryFilter.tsx

  const categoriesMap = use(categoriesPromise);
  const [isPending, startTransition] = useTransition();
  const [categories, setCategories] = useQueryState(
    'category',
    searchParams.category.withOptions({
      shallow: false,
      startTransition,
    }),
  );

  return (
    <div data-pending={isPending ? '' : undefined}>
      <ToggleGroup
        toggleKey="category"
        options={Object.values(categoriesMap).map(category => {
          return {
            label: category.name,
            value: category.id.toString(),
          };
        })}
        selectedValues={categories}
        onToggle={newCategories => {
          setCategories(newCategories);
        }}
      />

//searchParams.ts

import { parseAsString, createSearchParamsCache, parseAsArrayOf } from 'nuqs/server';

export const searchParams = {
  category: parseAsArrayOf(parseAsString).withDefault([]),
  q: parseAsString.withDefault(''),
};
export const searchParamsCache = createSearchParamsCache(searchParams);

I'm not sure what I'm doing wrong here; however, I'm pretty new to Nuqs.
Note: I can fix the behavior by wrapping the query state in useOptimistic, but this seems like the wrong approach.

...
const [optimisticCategories, setOptimisticCategories] = useOptimistic(categories);
...
selectedValues={optimisticCategories}
    onToggle={newCategories => {
      startTransition(() => {
        setOptimisticCategories(newCategories);
        setCategories(newCategories);
      });

Repo with full code: https://github.com/aurorascharff/next15-filterlist/blob/filter-nuqs/components/CategoryFilter.tsx

[franky47]

Thanks, I managed to reproduce it locally.

TL;DR: I think this can be escalated to a bug, which has to do with the sync mechanism nuqs uses internally to follow updates of the internal state of the app router (ie: when useSearchParams changes, whether via shallow navigation or router calls).

Let's take the example of starting from a blank URL http://localhost:3000/todo, and clicking the first two categories in order (Infrastructure, then Frontend).

Looking at the logs, we can see the following:

Sequence of events

First button clicked (Infrastructure)

1. The categories state is immediately set to ["0"], as part of nuqs' built-in optimistic update mechanism: update the internal state as if it was a useState (which it is), then queue an update of the URL.
2. The URL update is sent via router.replace (shallow: false). This triggers an RSC network call: http://localhost:3000/todo?category=0&_rsc=fvspk
3. The URL is shallow-updated to http://localhost:3000/todo?category=0 (using history.replace) to optimistically render the pending search param. This is to avoid waiting for the server response to see the URL update. We'll come back to this bit in a moment.

At this stage:

• The URL is http://localhost:3000/todo?category=0
• The categories state is ["0"]
• The RSC request is in flight and simulating a delay

Second button clicked (Frontend)

1. The categories state is immediately set to ["0","1"]
2. The URL update is sent and triggers an RSC network call: http://localhost:3000/todo?category=0%2C1&_rsc=56mlm
3. The URL is shallow-updated to http://localhost:3000/todo?category=0,1

At this stage:

• The URL is http://localhost:3000/todo?category=0,1
• The categories state is ["0","1"]
• Both RSC requests are in flight and simulating a delay

First RSC request resolves

This is where the problems start to occur. The first RSC request (with ?categories=0) coming back triggers a few renders, where useSearchParams (which is used by nuqs internally) returns, in sequence:

{ categories: '0,1' } // correct
{ categories: '0' } // incorrect
{ categories: '0' } // incorrect
{ categories: '0,1' } // correct
(and a few more correct re-renders)

Those incorrect values for useSearchParams could be due to the RSC payload changing the internal state of the app router. We can actually see the URL flickering too.

The problem that causes the visual flicker of the button is that nuqs picks up the incorrect update and syncs onto it (setting the categories state to ["0"]), but somehow skips syncing back on the correct one.

Second RSC request resolves

And resets everything back to normal (eventual consistency)

[franky47]

I've got a partial fix in #718 that works on your example, but it breaks a few other cases (history: push and support for startTransition) so I'll have to iterate on a better way (it might involve useOptimistic, since that's what we're trying to do with the URL).

If you want to try it:

npm i https://pkg.pr.new/nuqs@a5434acd4d6d5c6b963a7a9a344b907d7c157fd0

[franky47]

FYI, I just watched your talk at Next.js conf and realised this is the app you were presenting, that talk was amazing!

[aurorascharff]

Thanks for taking the time to look at this!

And I’m happy you enjoyed the talk, I’m actually currently writing a blog post «continuing» the demo to a useoptimistic provider and then to nuqs as the final result.

The demo i am doing will discard the first filters if you click the categories and also search the same time because they are in separate transitions! That’s why I’m ending up with nuqs 🥰

[franky47]

That's great to hear!

I'm not yet super familiar with using all those newer APIs, so can I ask you: when setting multiple individual useQueryState values that each have a startTransition option, those will be composed (nested, by order of call), do you think this is the right way to do this?

Also, those startTransitions only wrap the router call, not the internal state update, so in some cases you'd still need to use useDeferredValue for performance optimisations (expensive render tree). You could still wrap the whole state update in a standalone startTransition though.

[aurorascharff]

I'm not entirely sure if I can help here...

If you set multiple query params inside a transition, they're supposed to be batched before the UI updates. I did however experience bugs with this recently, and Sam filed a bug report on it: vercel/next.js#70977

[franky47]

@aurorascharff Thanks for the link, I'll have a look.

I'm trying to replicate your setup in my test environment, but I'm hitting some other issues: useTransition gets stuck in a loading state if I'm passing a Promise as props for the client component to unwrap with use (if the Promise is created in the render lifecycle of the parent RSC, a stable module-level promise works fine). That's with Next 14 though, I'll try it with the latest canary.

Edit: confirmed it was only an issue in Next.js 14, loading state resets correctly in 15.

[franky47]

I think I have a fix in #718 ! Could you try this please and let me know if it works for you? (it works on my local copy of your filter list app):

npm i https://pkg.pr.new/nuqs@9b07e04ec6295f592d2e4624f0837166f96928c1

The fix was to wrap the useSearchParams used by nuqs in a useOptimistic, so that it doesn't need to sync against temporary/stale updates coming from RSCs. The internal state follows the optimistic URL shallow update, and when the RSC payloads finish streaming in, everything is consistent in the app router state, but doesn't impact userland code (unless you use the stock useSearchParams alongside nuqs hooks, in which case they do get out of sync while RSC requests are pending).

[franky47]

🎉 This issue has been resolved in version 2.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

[aurorascharff]

That makes sense! That's what I did to fix it as well! :D I will try it now.

[aurorascharff]

Yep, works beautifully :) Of course I can't guarantee everything else with nuqs works after implementing this but for sure my case has been solved!