Debugging

Browser

You can enable debug logs in the browser by setting the debug item in localStorage to nuqs, and reload the page.

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

Log lines for both useQueryState and useQueryStates will be prefixed with [nuq+], along with other internal debug logs.

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. Hooks like useQueryState and useQueryStates can run on the server in these contexts. 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. 🙏