v2.0.1

2.0.1 (2024-10-22)

Bug Fixes

• Add back the .js extension to the pages router adapter (#694) (cd5bec1) - Thanks @tiagoskaneta !
• Mark framework packages as optional peer dependencies (#697) (df9e834) - Thanks @nezouse !

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/parsers to nuqs/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.
• UseQueryStatesOptions is 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 startTransition option no longer
  automatically sets shallow: false. The Options type
  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 from nuqs/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 nuqs name.

The debugging printouts no longer check for next-usequerystate, only nuqs.

• the following deprecated APIs have been removed:

• queryTypes bag of parsers -> use individual parseAsXYZ parsers
  for better tree-shakeability.
• subscribeToQueryUpdates helper -> since Next.js 14.0.5,
  useSearchParams is 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 !

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') 
}

Misc changes

• Drop mirrorring to next-usequerystate (abcbfdc)
• ESM only (drop CJS support) (b515c79)
• Remove deprecated APIs (5dd12c9), closes #425
• Rename nuqs/parsers to nuqs/server (ad3aa48)
• Update list of supported versions (9187252)

v1.20.0

1.20.0 (2024-10-07)

Features

• Allow remapping keys in useQueryStates (#671) (79f80da)
• serializer: allow null to clear all param values from base (#657) (0e7395e) - Thanks @neefrehman !

v1.19.3

1.19.3 (2024-09-26)

Bug Fixes

• Allow serializers to operate on derived UrlSearchParams classes (#647) (5dbbb1d) - Thanks @neefrehman!
• Handle Promises for the searchParams page prop (#652) (63d01eb)

v1.19.2

1.19.2 (2024-09-23)

Bug Fixes

• Serialization of default values in createSerializer (#642) (a1aa096) - Thanks @hugotiger !

v1.19.1

1.19.1 (2024-09-05)

Bug Fixes

• Cache the query string in useQueryStates (#631) (9dc148f) - Thanks @firatciftci !

v1.19.0

1.19.0 (2024-09-02)

Bug Fixes

• Allow parser-level options in useQueryStates (#621) (099ceb3), closes #618
• Ensure referential stability for values (#617) (6f22280)

Features

• Allow clearing all search params managed by useQueryStates (#622) (4c335a5)

v1.19.0-beta.1

1.19.0-beta.1 (2024-09-02)

Bug Fixes

• Allow parser-level options in useQueryStates (#621) (099ceb3), closes #618
• Ensure referential stability for values (#617) (6f22280)

Features

• Allow clearing all search params managed by useQueryStates (#622) (4c335a5)

v1.18.0

1.18.0 (2024-08-30)

Features

• Add parser type inference helpers (#578) (e2c88a6), closes #571