Server-side `clearOnDefault` and `urlKeys`

[anaclumos]

Context

What's your version of nuqs?

1.20.0

Next.js information (obtained by running next info):

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.1.0: Mon Sep 30 00:08:37 PDT 2024; root:xnu-11215.40.63~39/RELEASE_ARM64_T6030
  Available memory (MB): 18432
  Available CPU cores: 11
Binaries:
  Node: 22.3.0
  npm: 10.8.1
  Yarn: 1.22.22
  pnpm: 9.11.0
Relevant Packages:
  next: 14.2.15 // Latest available version is detected (14.2.15).
  eslint-config-next: N/A
  react: 18.3.1
  react-dom: 18.3.1
  typescript: N/A
Next.js Config:
  output: N/A

Are you using:

• ✅ The app router
• ❌ The pages router
• ❌ The basePath option in your Next.js config
• ❌ The experimental windowHistorySupport flag in your Next.js config

Description

How can I use clearOnDefault and urlKeys? Or to be more precise, I want to have a one single-source-of-truth, next to, for example, this:

import {
  parseAsFloat,
  createSearchParamsCache
} from 'nuqs/server'

export const coordinatesParsers = {
  lat: parseAsFloat.withDefault(45.18),
  lng: parseAsFloat.withDefault(5.72)
}
// Set `clearOnDefault` and `urlKeys` here somewhere of the configs?

export const coordinatesCache = createSearchParamsCache(coordinatesParsers)

[franky47]

The clearOnDefault can be applied per-parser using parseAsFloat.withOptions, though it won't do anything on the server: it's a URL update options (maybe we should make this more clear in the docs).

Regarding urlKeys, at the moment it's only implemented in useQueryStates (see #672), and I agree that having a single source of truth would be the best way. I'm not sure what kind of API that would look like, open to suggestions and PRs.

[anaclumos]

I guess I'll export an object at that file with all of the configs for now. Would see some sort of "global" option or "parser-specific-global" option so that I don't need to pass around the same object over and over.

[anaclumos]

Great work btw, been sponsoring you!

[franky47]

Thank you for the sponsorship! 🙏

Would see some sort of "global" option

This is coming after V2 lands, in the form of overridable global defaults for options. The adapters (which are a context provider) will forward them to the hooks, so it should look something like:

<NuqsAdapter globalOptions={{ clearOnDefault: false }} >
  {children}
</NuqsAdapter>

Also please note that clearOnDefault will be set to true by default in V2, per user feedback.

[franky47]

:tada: This issue has been resolved in version 2.1.0 :tada:

The release is available on:

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