unstale

npm / nuqs

nuqs

What changed in nuqs 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.

5 breaking5 new APIs and options1 performance7 behavior and defaults35 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.1.1 on npm

nuqs 253 changes

Breaking changes 5

New APIs and options 5

  • The React adapter can seed SSR search params via serverSearch.

    2.10.0release notes

  • Adds history to adapters’ defaultOptions.

    2.9.0release notes

  • Adds support for React Router v8.

    2.9.0release notes

  • Export the CreateLoaderOptions type so developers can use it in their code.

    2.8.6release notes

  • Adds support for React Router v5.

    2.8.0release notes

Performance 1

Behavior and default changes 7

  • The debounce callback is passed at push time.

    2.10.0release notes

  • Query keys on the Object prototype are supported.

    2.9.5release notes

  • Server runtimes that do not provide process are supported.

    2.9.5release notes

  • Updates location.search synchronously.

    2.9.0release notes

  • Server-side debug detection now uses process.env.DEBUG.

    2.8.9release notes

  • Passing undefined means leave the value as-is in useQueryStates.

    2.8.5release notes

  • Makes boolean parsing case insensitive.

    2.7.3release notes

Fixes and other changes 35

  • Flushed queue values are kept until the adapter shows them.

    2.10.2release notes

  • Pending query state stays in its transition lane.

    2.10.2release notes

  • Render once on mount when the URL contains a value.

    2.10.1release notes

  • Recover state after a navigation render is discarded.

    2.10.1release notes

  • The testing adapter's URL update queue is reset once per mount.

    2.10.1release notes

  • React adapter queues are reset on popstate.

    2.10.0release notes

  • Fragment-only history updates preserve the query.

    2.9.6release notes

  • Pending URL updates are canceled on history navigation.

    2.9.6release notes

  • Fragments are ignored in query-only URLs.

    2.9.6release notes

  • Comma-separated values are distinguished from repeated query keys.

    2.9.5release notes

  • Explicit empty native arrays are preserved.

    2.9.5release notes

  • The queue recovers after URL middleware errors.

    2.9.5release notes

  • Reactivity now works for startTransition callbacks.

    2.9.5release notes

  • Negative hexadecimal values round-trip correctly.

    2.9.4release notes

  • Credentials are preserved in URL serializer bases.

    2.9.4release notes

  • Options and defaults are refreshed correctly.

    2.9.4release notes

  • Preserves query state across concurrent rebases.

    2.9.3release notes

  • Recovers state after a render is discarded.

    2.9.2release notes

  • Supports multi-value search params in createSearchParamsCache.

    2.9.1release notes

  • Preserves the hash fragment in createSerializer bases.

    2.9.1release notes

  • Fixes unwatched keys leaking through filterSearchParams.

    2.9.1release notes

  • Applies call > parser > global precedence for limitUrlUpdates.

    2.9.1release notes

  • Transitions remain pending while React Router loaders run.

    2.9.1release notes

  • Fixes stale values under Activity.

    2.9.0release notes

  • Fixes incorrect transient state when updating in useEffect.

    2.9.0release notes

  • Fixes stale URL values when revisiting a page under Next.js cacheComponents.

    2.9.0release notes

  • Fixes stale search parameters leaking across React Router navigation.

    2.9.0release notes

  • Fixes cross-page transitions in TanStack Router.

    2.9.0release notes

  • Prevents infinite re-renders with TSR viewport preloading.

    2.9.0release notes

  • Resets the queue after updates in the Next.js app router.

    2.8.8release notes

  • React Router adapters now wait for navigation before syncing.

    2.8.7release notes

  • The directive was removed from .d.ts definition files.

    2.8.4release notes

  • Forwards processUrlSearchParams through the debounce queue.

    2.8.3release notes

  • Pass the full pathname and search in TSR to avoid trailing slashes.

    2.8.1release notes

  • Fixes a TypeError in the serializer when an array has a default value.

    2.7.3release notes