Node 25 warning on import: `--localstorage-file` was provided without a valid path

[PaulRBerg]

Context

What's your version of nuqs?

nuqs@2.8.8

What framework are you using?

• ✅ Next.js (app router)
• ❌ Next.js (pages router)
• ❌ React SPA (no router)
• ❌ Remix
• ❌ React Router
• ❌ Other

Which version of your framework are you using?

next@16.1.6
react@19.2.4

Additional environment:

node v25.6.0
macOS (arm64)

Description

Importing nuqs/server on Node 25 emits this warning:

(node:XXXX) Warning: `--localstorage-file` was provided without a valid path
    at Object.get (node:internal/webstorage:32:25)

In my app this appears during next dev (Turbopack) because server code imports nuqs/server for createSearchParamsCache.

From tracing, this happens at module evaluation time in nuqs debug code (isDebugEnabled) that probes localStorage.

Reproduction

Minimal Node-only repro (no Next required):

mkdir nuqs-node25-repro && cd nuqs-node25-repro
npm init -y
npm i nuqs@2.8.8
NODE_OPTIONS=--trace-warnings node -e "import('nuqs/server').then(() => console.log('loaded'))"

Observed output includes:

loaded
(node:...) Warning: `--localstorage-file` was provided without a valid path
    at Object.get (node:internal/webstorage:32:25)
    at isDebugEnabled (node_modules/nuqs/dist/server.js:...)

Expected:

• Importing nuqs/server in a server/runtime context should not touch localStorage at module top-level.
• No Node webstorage warning should be emitted.

Potential direction:

• Gate debug-localStorage checks behind typeof window !== 'undefined' (or defer the check to client-only paths).

[franky47]

Thanks, it may also be relevant to update the debug detection code to handle backend cases (eg: reading from the DEBUG env var).

Would you like to open a PR?

[PaulRBerg]

not able to dedicate time to a PR at this time, but I will open one if I keep bumping into this error later on.