Nuqs rerender count in NextJS

[alberto-htl]

Context

What's your version of nuqs?

2.2.3

What framework are you using?

• ✅ Next.js (app router)

Which version of your framework are you using?

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.4.0: Fri Mar 15 00:12:49 PDT 2024; root:xnu-10063.101.17~1/RELEASE_ARM64_T6020
  Available memory (MB): 16384
  Available CPU cores: 10
Binaries:
  Node: 18.19.0
  npm: 10.2.3
  Yarn: 1.22.21
  pnpm: 8.11.0
Relevant Packages:
  next: 15.1.2 // Latest available version is detected (15.1.2).
  eslint-config-next: 15.1.2
  react: 19.0.0
  react-dom: 19.0.0
  typescript: 5.7.2
Next.js Config:
  output: N/A

Description

The component is rerender 8 times while the component with the default hooks of nextjs is rerendered only 2 times.

Expected behavior is to both component rerender the same amount of times.

The demo offer two components one using the nextjs hooks directly, and another using useQueryState from nuqs.

To test it, use the button. Test the nextjs component and check the console logs. Then use the button on the component that use nuqs and check the console logs.

Reproduction

https://github.com/dev2xl/nuqs-rerender-demo

[franky47]

Updating the URL is an asynchronous operation, and nuqs does optimistic state updates to keep the UI responsive, so having more renders than with a simple synchronous, local useState, is expected. 8 times feels a little high though.

Your reproduction repo is just a stock create-next-app, did you forget to push a commit?

See also: #516.

[alberto-htl]

@franky47 Sorry for the confusion earlier. I've updated the repo; could you please take a look?

Just to clarify, the comparison here is not with useState, but rather with the behavior we're seeing when using useRouter, useParams, and URLSearchParams (similar to how Nuqs handles routing). With these hooks, the component re-renders only twice per update. However, with Nuqs, we’re seeing around 8 renders per update.

Can you check the console logs during the tests to help track this?

When we set shallow to false, the number of renders drops to 6, but ideally, I’d expect the render count to be similar to the two renders we'd see in a typical server-side rendering setup, right?

My primary use case here is a data table where I’d prefer not to update optimistically, since the data is coming from the server. My goal is to minimize these costly re-renders.

Let me know what you think, and thanks for your help!

[franky47]

Hey, I managed to take a look at your repro, and I can only see 4 renders (the doubles you see are due to StrictMode). You can see only four when building for production.

There might be something I can do to reduce it to 3, see #755 (comment).

[franky47]

@alberto-htl I did some render counts in #849, and fixed a couple of issues that could have caused extra renders. It should be more stable at 2 renders on shallow: true and 3 renders on shallow: false in the app router.

Feel free to try [email protected] and let me know if it helps.

[alberto-htl]

@franky47 That's great! I will take a look. Thank you for your support