v2.0.0-beta.1
Pre-release
2.0.0-beta.1 (2024-01-18)
Breaking changes / Migration guide
Dropped support for [email protected]
It may seem weird to drop support for a single patch version, and keep it for older versions, but this is due to a bug in shallow routing in Next.js 14.0.3 that was fixed in 14.0.4, and that became hard to work around without ugly hacks as Next.js releases evolved.
See #423 for context and a table of supported versions.
ESM only
[email protected] is now an ESM-only package. This should not be much of an issue since Next.js supported ESM since version 12, but if you are bundling nuqs code into an intermediate CJS library to be consumed in Next.js, you'll run into import issues. Outside of converting your library to ESM (future-proof), your main option is to dynamically import nuqs:
const { useQueryState } = await import('nuqs')Deprecated exports
Some of the v1 API was marked as deprecated back in September 2023, and has been removed in [email protected].
queryTypes parsers object
Replace with parseAsXYZ to match, for better tree-shakeability:
- import { queryTypes } from 'nuqs'
+ import { parseAsString, parseAsInteger, ... } from 'nuqs'
- useQueryState('q', queryTypes.string.withOptions({ ... }))
- useQueryState('page', queryTypes.integer.withDefault(1))
+ useQueryState('q', parseAsString.withOptions({ ... }))
+ useQueryState('page', parseAsInteger.withDefault(1))subscribeToQueryUpdates
Next.js 14.0.5 makes useSearchParams reactive to shallow search params updates, which makes this internal helper function redundant. See #425 for context.
Renamed nuqs/parsers to nuqs/server
When introducing the server cache in #387, the dedicated export for parsers was reused as it didn't include the "use client" directive. Since it now contains more than parsers and probably will be extended with server-only code in the future, it has been renamed to a clearer export name.
Find and replace all occurrences of 'nuqs/parsers' to 'nuqs/server' in your code:
- import { parseAsInteger, createSearchParamsCache } from 'nuqs/parsers'
+ import { parseAsInteger, createSearchParamsCache } from 'nuqs/server'Debug printout detection
After the rename to nuqs, the debugging printout detection logic handled either next-usequerystate or nuqs being present in the localStorage.debug variable. In [email protected] it only checks for the presence of the nuqs substring to enable logs. Update your local dev environments to match by running this once in the devtools console:
if (localStorage.debug) {
localStorage.debug = localStorage.debug.replace('next-usequerystate', 'nuqs')
}