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 next@14.0.3

Due to a bug in the implementation of shallow routing (WHS),
14.0.3 required a special case for syncing
against external navigation.

In nuqs@2.x, 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 !