feat: defaultOptions for NuqsAdapter

[TkDodo]

This PR adds defaultOptions to <NuqsAdapter>, which allows to override the globally specified defaults.

As a first step, only shallow?: boolean can be provided, but it can be extended to more default values.

[vercel]

@TkDodo is attempting to deploy a commit to the 47ng Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Project	Deployment	Preview	Comments	Updated (UTC)
nuqs	✅ Ready	Preview	Comment	Aug 14, 2025 1:52pm

[pkg-pr-new]

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

commit: a070303

[franky47]

Thanks, it looks good, I'd be more generic about the AdapterDefaultOptions type to allow extending it in the future with other props passed via the adapter (like a callback function to process URLSearchParams after applying updates for alphabetical sorting).

I don't think it's an issue, but could passing an object from the render body cause re-renders? I guess as long as the parent component of <NuqsAdapter> isn't re-rendered it shouldn't be an issue, and that would cause the whole app to re-render anyway (as adapters are placed high in the tree).

function RootLayout({ children }) {
  return (
    <NuqsAdapter defaultOptions={{ shallow: false })>
      {children}
    </NuqsAdapter>
  )
}

[franky47]

nitpick: There are other things we could pass through that Context from adapter props, so this type could be more generically named AdapterProps, what do you think?

[TkDodo]

yeah that makes a lot of sense. AdapterDefaultOptions is actually the defaultOptions object inside the AdapterProps 👍

5025028

[TkDodo]

@franky47 regarding re-renders: currently, the context value is not memoized - it’s a new object with useAdapter inside:

nuqs/packages/nuqs/src/adapters/lib/context.ts

Line 42 in aa902c2

{ ...props, value: { useAdapter } },

so that alone could cause re-renders. However, that’s only a concern IF the RootLayout in your example would render “from within itself”, because then children would be stable.

If there’s a top-down render, children will be new and will therefore always re-render the whole tree downwards.

[github-actions]

🎉 This PR is included in version 2.5.0-beta.5 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 2.5.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[Multiply]

(like a callback function to process URLSearchParams after applying updates for alphabetical sorting).

Is this feature planned? We're definitely looking for this feature specifically. (alphabetical sorting of parameters)
Edit: or a callback where we can do it ourselves.

[franky47]

@Multiply would you like to try your hand at a PR?

[Multiply]

@Multiply would you like to try your hand at a PR?

Was already looking into the recent introduction of global default config.
Do you have a preference for where the middleware should be called?

[franky47]

Let's continue the discussion in #1109.