feat: nuqs@2.0.0

[franky47]

Planned to coincide with the release of Next.js 15.

Now that 14.1.2 has been released with most bugs ironed out, this PR is clear on the Next.js dependency side.
Edit: React 19 has joined the chat

Will include the following breaking changes:

• Remove deprecated exports
• ESM only - chore: ESM only (drop CJS support) #458
• Rename the parsers export to server
• fix: Deprecate subscribeToQueryUpdates #425
• feat: Introducing adapters for other frameworks #644
• Drop updates to next-usequerystate, migrate to nuqs - Project rebranding to `nuqs` #438
• Remove mentions of next-usequerystate everywhere (log localStorage check)
• Add migration docs

Tasks

• Merge feat: Introducing adapters for other frameworks #644 in here
• parseAsJson: make it return unknown and/or make the validation argument required (see poll)
• See what kind of story Next.js 15 has for peer-dep'ing React 19.
• Update branch protection to remove deprecated versions before merge
• update docs to indicate current behaviour (remove upcoming)

Migration guide

Read it online: https://nuqs.47ng.com/docs/migrations/v2

Support moved to next@>=14.2.0

Early versions of Next.js 14 were in flux with regards to shallow routing, only from 14.2.0 is it stable enough to not require ugly hacks.

See #423 for context and a table of supported versions.

ESM only

nuqs@2.0.0 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 nuqs@2.0.0.

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 nuqs@2.0.0 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') 
}

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nuqs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 22, 2024 11:38am

[github-actions]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀