How to intercept route changes caused by setting a query param value

[ryanhopperlowe]

Hello, I love using nuqs for manipulating next query params, but I've run into an issue where I'm unable to intercept url changes when query params are updated using the setter method in useQueryState

I'm attempting to run some code like this:

In one component, I'm listening for route changes in the router (I'm using the pages router, so useRouter is imported from next/router)

  const router = useRouter()

  useEffect(() => {
    const handleRouteChange = (nextPath: string) => {
      console.log(nextPath)
      // check conditions and optionally block navigation
    }

    router.events.on('routeChangeStart', handleRouteChange)

    return () => {
      router.events.off('routeChangeStart', handleRouteChange)
    }
  }, [])

Then in another component, I am using nuqs to update the value of a url param

  const [param, setParam] = useQueryState(
    paramName,
    parseAsString.withDefault(defaultValue)
  )

  const updateParam = (value: string) => {
    setParam(value)
  }

After diving into nuqs, I found that it's not using router['push' | 'replace'] but is instead calling history.replaceState and history.pushState respectively to update the url. As a result, there is no router event being fired inside of next.

Is there a workaround for this, or would this be considered a bug in the code? I'll unfortunately have to abandon the library if I can't get a solution to this issue.

Thanks so much!

versions:

• NextJS: 13.5.6 (pages router)
• nuqs: 1.15.4

[franky47]

I replicated your setup, and I do get events.

router-events.mov

Here's the complete page code:

import { NextRouter, useRouter } from 'next/router'
import { parseAsInteger, useQueryState } from 'nuqs'
import React from 'react'

declare global {
  interface Window {
    next?: {
      version: string
      router?: NextRouter & {
        state: {
          asPath: string
        }
      }
    }
  }
}

export default function Page() {
  const [, setCount] = useQueryState('count', parseAsInteger.withDefault(0))
  const router = useRouter()

  React.useEffect(() => {
    const handleRouteChange = (nextPath: string) => {
      console.log('router: %s', nextPath)
      // check conditions and optionally block navigation
    }
    router.events.on('routeChangeStart', handleRouteChange)
    return () => {
      router.events.off('routeChangeStart', handleRouteChange)
    }
  }, [])

  React.useEffect(() => {
    const handleRouteChange = (nextPath: string) => {
      console.log('nuqs router: %s', nextPath)
      // check conditions and optionally block navigation
    }
    window.next?.router?.events.on('routeChangeStart', handleRouteChange)
    return () => {
      window.next?.router?.events.off('routeChangeStart', handleRouteChange)
    }
  }, [])

  return <button onClick={() => setCount(c => c + 1)}>Test</button>
}

A few things to note:

1. nuqs only uses the History API for shallow updates in the app router. In the pages directory, search param updates use the pages router instance available under window.next.router, as using the compat layer exposed in next/navigation wasn't good enough (bugs with basePath, and no support for events in your case).
2. The pages router events docs don't mention a way to block navigation, those event handlers are only here for notification of what happens. It sounds like a middleware would be a more appropriate solution to allow/deny navigation, though be aware that nuqs updates are shallow by default, and so will not go through the middleware.

[ryanhopperlowe]

Hi @franky47 Thanks so much for the timely reply. I've spent several hours on this, and I realized that my use case is actually more specific.

Essentially I'm using router events to display a confirmation modal when a user tries to update the url. The confirmation modal is only rendered when specific conditions are met (in this scenario, when ?willBlockNavigation=true). The problem was actually caused because the source of truth from nuqs seems to be its own internal state (NOT the url value). As a result, when the nuqs setter method is called, it is removing the router event listener BEFORE the url is updated, which explains why the modal didn't display for me when a user updates another query param.

In the code below, line 12 causes the unexpected behavior, while line 40 fixes the issue.

import React, { useCallback, useEffect, useState } from "react"
import { useRouter } from "next/router"
import { parseAsBoolean, useQueryState } from "nuqs"

export default function Home() {
  const [fromNuqs, setCanBlock] = useQueryState(
    "willBlockNavigation",
    parseAsBoolean.withDefault(false)
  )

  // uncomment next line to see unexpected behavior
  // const shouldBlock = fromNuqs // This causes blocking to occur on first render
  /**
   * The problem here is because the nuqs state seems to be updated BEFORE the router
   *
   * It seems like events are happening in this order
   * 1. Button Clicked
   * 2. setCanBlock(true) is called (should not be blocked because `canBlock` is false)
   * 3. Nuqs state is updated (triggers rerender)
   * 4. ConfirmNavigationModal is rendered and adds event listener
   * 5. Router event is triggered which triggers listener
   *
   * The inverse of this is also true
   * 1. Button Clicked
   * 2. setCanBlock(false) is called (should get blocked because `canBlock` is true)
   * 3. Nuqs state is updated (triggers rerender)
   * 4. ConfirmNavigationModal is unmounted, removing event listener
   * 5. Router event gets triggered
   * 6. Router event does NOT get blocked
   * Here the listener is removed before the router event is triggered, so it doesn't block as expected
   */

  const router = useRouter()
  const fromRouter = parseAsBoolean.parse(
    (router.query.willBlockNavigation as string) || "false"
  )

  // uncomment next line to see expected behavior
  const shouldBlock = fromRouter // This gives desired

  /**
   * The line above works perfectly because the router state is treated as the source of truth
   *
   * 1. Button Clicked
   * 2. setCanBlock(true) is called (should not be blocked because `canBlock` is false)
   * 3. Router event is triggered (no listener yet)
   * 4. Url is updated (triggers rerender)
   * 5. ConfirmNavigationModal is rendered and adds event listener
   *
   * Next time through
   * 1. Button Clicked
   * 2. setCanBlock(false) is called (should get blocked because `canBlock` is true)
   * 3. Router event is triggered (listener exists)
   * 4. ConfirmNavigationModal is triggered (expected)
   */

  return (
    <>
      <button onClick={() => setCanBlock((prev) => !prev)}>Update URL</button>
      <br />
      {shouldBlock && <span>Popup SHOULD occur on next click</span>}
      {shouldBlock && <ConfirmNavigationModal />}
    </>
  )
}

function ConfirmNavigationModal() {
  const router = useRouter()
  const [nextPath, setNextPath] = useState<string | null>(null)

  const handleRouteChange = useCallback((nextPath: string) => {
    console.log("onRouteChange", nextPath)

    setNextPath(nextPath)

    throw "ignore error: block navigation"
  }, [])

  const addListener = () => {
    console.log("addListener")

    router.events.on("routeChangeStart", handleRouteChange)
  }

  const removeListener = () => {
    console.log("removeListener")

    router.events.off("routeChangeStart", handleRouteChange)
  }

  useEffect(() => {
    addListener()
    return removeListener
  }, [])

  const handleConfirm = () => {
    if (!nextPath) return

    removeListener()
    router.push(nextPath)
    setNextPath(null)
  }

  const handleCancel = () => {
    setNextPath(null)
  }

  return (
    <div>
      <dialog open={!!nextPath}>
        <div>Are you sure?</div>
        <button onClick={handleCancel}>No</button>
        <button onClick={handleConfirm}>Yes</button>
      </dialog>
    </div>
  )
}

The problem here is that it seems the url is not the actual source of truth. Luckily I was able to find this workaround and while it's simple enough, it was very obscure and difficult to intuit. It might be worth allowing a developer to choose their source of truth as a config value, or at least adding it to the README that url changes are only triggered AFTER the internal state is updated.

Thanks again for your help, I hope this is helpful!!