update a.k.a setter function is not stable in v2

[SaveliiLukash]

Context

What's your version of nuqs?

"nuqs": "2.3.0"

What framework are you using?

✅ Next.js (app router)

Which version of your framework are you using?

"next": "15.1.4",
"react": "^19.0.0",
"react-dom": "^19.0.0"

Description

nuqs update function a.k.a setter in useQueryState(s) is no longer stable (by reference) in v2 in contrast to v1

v1 perfectly aligns with react's own useState the setState of which is guaranteed to be stable
v2 breaks this behavior

The following useEffect will run indefinitely in a loop in v2, but not in v1:

  const [,setUsername] = useQueryState("username")

  useEffect(() => {
    console.log("Running setUsername")
    setUsername(null)
  }, [setUsername]);

Reproduction

I set up a simple next.js starter repo with nuqs and hosted it on Vercel:

V2: GitHub v2 | Vercel v2
v1: GitHub v1 | Vercel v1

1. Open the page
2. Note the console output Running setUsername printed in an infinite loop to console in v2
3. Note the console output Running setUsername printed once only in v1
4. The app crashes in Firefox after some time due to History API overload (not on video, but reproducable)

Demo:

CleanShot.2025-01-08.at.21.23.52.mp4

The point of interest is NUQS component.

Research

The update function in v1 had the following dependency array, which works just fine:

nuqs/packages/nuqs/src/useQueryState.ts

Line 313 in 79f80da

[key, history, shallow, scroll, throttleMs, startTransition]

The v2 has introduced adapter to the dependency array:

nuqs/packages/nuqs/src/useQueryState.ts

Line 297 in 10e526d

[key, history, shallow, scroll, throttleMs, startTransition, adapter]

adapter is a context value which is a composite object:

nuqs/packages/nuqs/src/adapters/next/impl.app.ts

Lines 42 to 47 in 10e526d

	return {
	searchParams: optimisticSearchParams,
	updateUrl,
	// See: https://github.com/47ng/nuqs/issues/603#issuecomment-2317057128
	rateLimitFactor: 2
	}

In this context updateUrl is stable locally thanks to an empty dependency array ([]) of useCallback

nuqs/packages/nuqs/src/adapters/next/impl.app.ts

Lines 40 to 41 in 10e526d

	}
	}, [])

However the object that is return'ed is dynamic (recreated on every render)

return {
  searchParams: optimisticSearchParams,
  updateUrl,
  // See: https://github.com/47ng/nuqs/issues/603#issuecomment-2317057128
  rateLimitFactor: 2
}

Simplified React Example

Current context provider for nuqs adapters can be simplified to the following snippet, where compositeObjectValue, used by context consumers will not be stable:

function MyProvider({ children }) {
  const [value, setValue] = useState(0);

  // Use memo prevents object creation on every render
  // But it is still recreated on every `value` change
  const compositeObjectValue = useMemo(() => ({ value, setValue }), [value, setValue]);

  return (
    <MyContext.Provider value={compositeObjectValue}>
      {children}
    </MyContext.Provider>
  );
}

compositeObjectValue here represents adapter:

nuqs/packages/nuqs/src/useQueryState.ts

Line 297 in 10e526d

[key, history, shallow, scroll, throttleMs, startTransition, adapter]

Possible solutions

1. Update the dependency array of update function to rely on stable object values instead of a dynamic object itself (if possible):

- [key, history, shallow, scroll, throttleMs, startTransition, adapter]
+ [key, history, shallow, scroll, throttleMs, startTransition, adapter.updateUrl, adapter.rateLimitFactor]

2. Another common practice is splitting a context in two, for dynamic and stable values:

const ValueContext = createContext();
const SetterContext = createContext();

function MyProvider({ children }) {
  const [value, setValue] = useState(0);

  return (
    <ValueContext.Provider value={value}>
      <SetterContext.Provider value={setValue}>
        {children}
      </SetterContext.Provider>
    </ValueContext.Provider>
  );
}

3. If not possible to restore the v1 behavior, update the docs to reflect the breaking change and warn users not to use update function in dependency arrays.
   It also has to be stated that useQueryState's update does not align with useState's setState in terms of stability

Extra thoughts

From our side (as consumers of this library) a solution is to remove update functions of useQueryState(s) from all dependency arrays. It works just fine and having it specified is, probably, redundant in the first place.

However, placing a setter function in a dependency array is not a violation in any case and is perfectly fine according to React.

Eslit's react-hooks/exhaustive-deps highlights the need to add an update function to the dependency array, so that is what many devs might just do.

P.S. @franky47 Thanks for your work on this amazing library which is really helpful and is a pleasure to use! Looking forward to many years of collaboration!

[franky47]

Thanks for the detailed report! I fixed this in #841, could you give [email protected] a try and let me know if it works better? It also solves some unnecessary re-renders (see #849).

[SaveliiLukash]

Awesome! Tested this version both in demo examples and in our project which uses nuqs and can confirm that [email protected] fixes the issue! There is also a lot less renders which is nice.

We'll use 2.3.1-beta.2 for know and waiting for stable 2.3.1 release!

Thanks for your quick response and your work in general!

[franky47]

Good, let me know if you hit any snags with the beta, I'm planning on shipping 2.3.1 tomorrow.

[franky47]

[email protected] was released (somehow the Semantic Release bot didn't make the connection with this issue).