How to enable debug mode in nuqs?

#nuqs #opensource #nextjs #debug

In this article will review how to enable debug mode in nuqs.

we will look at,

Update localStorage
debug function declaration
debug function examples in nuqs codebase.

Update localStorage

in the nuqs documentation about the bugging you can enable debug logs and also use the timing markers by setting the debug item in local storage to nuqs and reload the page so you will have to well may be you could just open your browser console that is the dev tools and run this code

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

what it does is it will set the key as debug and the value as the nuqs and this happens this is something you could find in the local storage.

log lines will be prefixed with [nuqs] for usequerystate and [nuqs+] for along with other internal debug logs.

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

debug function declaration

import type { Options } from './defs'
import { error } from './errors'
import { getDefaultThrottle } from './utils'

export const FLUSH_RATE_LIMIT_MS = getDefaultThrottle()

type UpdateMap = Map<string, string | null>
const updateQueue: UpdateMap = new Map()
const queueOptions: Required<
  Omit<Options, 'startTransition' | 'clearOnDefault'>
> = {
  history: 'replace',
  scroll: false,

once you have the debug mode enabled obviously you will have to call this debug function in your codebase, so the way nuqs has this return or declared is that you will find the debug function in a file called debug.js that’s in nuqs package.

debug function accepts to parameters the first one is the message and the next one is its this spread oparater so basically that means that it can accept n number of parameters.

 if (!debugEnabled) {
    return
  }

At line number 7 you will see this function called sprintf it returns in the same file it does some operation using a regular expression but you have to remember that all it does says it returns a string now this string could either be stringify or just a plane string depending on a matching condition which is this

(match === '%O' && arg)

export function sprintf(base: string, ...args: any[]) {
  return base.replace(/%[sfdO]/g, match => {
    const arg = args.shift()
    if (match === '%O' && arg) {
      return JSON.stringify(arg).replace(/"([^"]+)":/g, '$1:')
    } else {
      return String(arg)
    }
  })
}

performance.mark there is another article where I wrote about performance.mark. Learn more about performance

https://developer.mozilla.org/en-US/docs/Web/API/Performance/now

Debug what it does is it just simply logs the message as you can see a line number 11.

   console.log(message, ...args)

along with the args that were passed to the debug function get logged so all the parameters that it send to the debug function basically get logged using console.log and if there is an error in logging this the error is passed and the message gets logged based on the string return by this sprintf.

 try {
    // Handle React Devtools not being able to console.log('%s', null)
    console.log(message, ...args)
  } catch (error) {
    console.log(msg)
  }
}

debug function examples in nuqs codebase

This debug function is used in a lot of places across the nuqs codebase.

Here’s is one example picked from patch-history.ts. At line no 61 debug function gets called with the message and n number of args so that all of this get logged in the debug mode is enabled

debug(
    '[nuqs %s] Patching history (%s adapter)',
    '0.0.0-inject-version-here',
    adapter
  )

Here is another example where the debug function is called and this is from usequerystate.ts file at line no 250 you will find the debug function is called with this message and then it also had to additional parameters

 debug('[nuqs `%s`] syncFromUseSearchParams %O', key, state)

About me:

Hey, my name is Ramu Narasinga. I study large open-source projects and create content about their codebase architecture and best practices, sharing it through articles, videos.

Configure features such as Changesets, Supabase auth in your Next.js project using Think Throo CLI.

Email — [email protected]

My Github — https://github.com/ramu-narasinga

My website — https://ramunarasinga.com

My YouTube channel — https://www.youtube.com/@ramu-narasinga

Learning platform — https://thinkthroo.com

Codebase Architecture — https://app.thinkthroo.com/architecture

Best practices — https://app.thinkthroo.com/best-practices

Production-grade projects — https://app.thinkthroo.com/production-grade-projects