Debugging

Browser

Start by importing the nuqs/debug entry point once in your app. This keeps the log messages out of your bundles unless you opt in. In frameworks with separate client and server bundles, import it in each runtime where you want logs.

// Once in your app:
import 'nuqs/debug'

Then set the debug item in localStorage to nuqs, and reload the page.

// In your devtools:
localStorage.setItem('debug', 'nuqs')

Log lines are prefixed with [nuq+ …] for hook-level messages, and [nuqs <subsystem>] for internal subsystems such as the throttle and debounce queues and adapters.

Note: unlike the debug package, this will not work with wildcards, but you can combine it: localStorage.setItem('debug', '*,nuqs')

Server (Node.js)

Debug logs apply in any Node environment: server-side rendering (SSR), React Server Components (RSC), or when using nuqs/server. Importing nuqs/debug from a server entry point, such as a Next.js root layout, brings the debug logs into your server bundle.

Enable logs by setting the DEBUG environment variable so it contains nuqs:

DEBUG=nuqs node server.js

Or when running your development server:

DEBUG=nuqs pnpm dev

You can also define DEBUG=nuqs in your .env file or configure it through your hosting environment.

Unlike the browser version, this does not use localStorage. Debug mode is enabled when process.env.DEBUG contains the string nuqs.

User timings markers are also recorded, for advanced performance analysis using your browser’s devtools.

Providing debug logs when opening an issue is always appreciated. 🙏