v2.0.0

2.0.0 (2024-10-22)

• Announcement post
• Migrations docs

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 !