Releases: 47ng/nuqs
v2.2.0
Contributors
Assets 2
v2.1.2
2.1.2 (2024-11-12)
Bug Fixes
- Log an error in development if URI size of 2000 characters is exceeded. (#747) (3017660) - Thanks @niklasbec !
- Use correct keys for state sync (#759) (6bc229a), closes #758 - Thanks @hallucinogenizer !
Contributors
Assets 2
v2.1.1
2.1.1 (2024-10-31)
Bug Fixes
- adapters/next/app: wrap optimistic search params update in startTransition (#729) (01af1ea) - Thanks @aryasaatvik !
Contributors
Assets 2
v2.1.0
2.1.0 (2024-10-30)
Bug Fixes
- Use optimistic search params in app router (#718) (b5c0168), closes #714 - Thanks @aurorascharff !
Features
- Add parseAsISODate (#707) (107fcc1) - Thanks @tylersayshi !
- Add support for urlKeys in cache (#725) (b8dcc6f), closes #720 - Thanks @anaclumos !
- Add urlKeys & clearOnDefault support for serializer (#720) (c701afd), closes #715 - Thanks @blechatellier !
- Export OnUrlUpdateFunction type for Vitest v2 (#712) (0645c51) - Thanks @bryanjtc !
- Export the SearchParams type in both client & server bundles (#710) (5a926f7)
Contributors
Assets 2
v2.0.4
v2.0.3
v2.0.2
v2.0.1
v2.0.0
2.0.0 (2024-10-22)
- Announcement post: https://nuqs.47ng.com/blog/nuqs-2
- Migrations docs: https://nuqs.47ng.com/docs/migrations/v2
Bug Fixes
- parseAsJson now requires a runtime validation function (53a37d4)
chore
- Drop mirrorring to next-usequerystate (4616a7b)
- ESM only (drop CJS support) (408fd38)
- Move urlKeys into the UseQueryStatesOptions type (8950bc8)
- Remove deprecated APIs (8d2ba24), closes #425
- Rename
nuqs/parserstonuqs/server(b6bdc66) - Update list of supported versions (9665a93)
- Update minimum supported Next.js version (c509a99), closes vercel/next.js#61419
Features
- Add adapter for One (a56aa11)
- Add custom adapters API (unstable) (3ef698f)
- Add React Router adapter (cb30a20)
- Add Remix adapter (4ae6c81)
- Add vanilla React adapter sandbox (e603a4d)
- Introducing adapters for other frameworks (a101370), closes #603 #620
- Provide specialised adapters for both Next.js routers (ac95384)
- Render pretty URLs in other adapters (6618f45)
BREAKING CHANGES
- Pass in a validation function like a Zod schema parse function
to validate at runtime and infer the type of the returned data. UseQueryStatesOptionsis now generic over the key map
(the object containing parser definitions you pass to useQueryStates),
and is now a type rather than an interface.- When using Next.js, nuqs v2 requires next@>=14.2.0.
- nuqs now requires wrapping your app
with a NuqsAdapter, which is a context provider connecting
your framework APIs to the hooks' internals. - The
startTransitionoption no longer
automatically setsshallow: false. TheOptionstype
is no longer generic. - The "use client" directive was not included
in the client import (import {} from 'nuqs'). It has now been added,
meaning that server-side code needs to import fromnuqs/server
to avoid errors like:
Error: Attempted to call withDefault() from the server but withDefault is on
the client. It's not possible to invoke a client function from the server, it can
only be rendered as a Component or passed to props of a Client
Component.
- Drop support for [email protected]
Due to a bug in the implementation of shallow routing (WHS),
14.0.3 required a special case for syncing
against external navigation.
In [email protected], we're cleaning this up and requiring
a version of Next.js with bug-free support for
shallow routing (with or without experimental WHS
in 14.0.4, and with stabilised WHS in 14.0.5 onwards).
- export path has been renamed. Contents are identical.
Since the /parsers export contained the server cache,
this name makes better sense and helps outline the client/server
nature of features in nuqs.
- package is now only updating on the
nuqsname.
The debugging printouts no longer check for next-usequerystate, only nuqs.
- the following deprecated APIs have been removed:
queryTypesbag of parsers -> use individualparseAsXYZparsers
for better tree-shakeability.subscribeToQueryUpdateshelper -> since Next.js 14.0.5,
useSearchParamsis reactive to shallow search params updates
- drop CJS support.
Since Next has ESM support since v12, it should not really be a breaking change for most.
Big thanks to @andreisocaciu, @tordans, @prasannamestha, @Talent30, @neefrehman, @chbg, @dopry, @weisisheng, @hugotiger, @iuriizaporozhets, @rikbrown, @mateogianolio, @timheerwagen, @psdmsft, and @psdewar for helping !
Contributors
Assets 2
v2.0.0-beta.1
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')
}