Add a global option to opt-out of shallow routing

[nygmaaa]

Context

"next": "14.2.22",
"nuqs": "^2.2.3",

Problem Description

Currently, nuqs uses history.replaceState/history.pushState in the App Router to implement shallow routing (https://github.com/47ng/nuqs/blob/next/packages/nuqs/src/adapters/next/impl.app.ts#L22-L30). However, this conflicts with the history.replaceState/history.pushState method overridden by Cloudflare's injected Zaraz script (Code below). The Zaraz script is beyond my control, leading to an issue when using nuqs in environments where Zaraz is present.

To address this, I found that opting out of shallow routing resolves the conflict (https://github.com/47ng/nuqs/blob/next/packages/nuqs/src/adapters/next/impl.app.ts#L35-L40). However, specifying { shallow: false } repeatedly throughout the codebase is both cumbersome and error-prone. It's also easy for team members to forget to include { shallow: false }, potentially introducing bugs.

Reproduction

codesandbox
https://codesandbox.io/p/sandbox/nuqs-reproduction-2sskwl

Proposed Solution

Introduce a global configuration option in nuqs that allows developers to opt-in or opt-out of shallow routing. This would enable teams to globally disable shallow routing without needing to explicitly specify { shallow: false } every time useQueryState(s) is used.

Benefits

• Resolves conflicts with overridden history.replaceState/history.pushState caused by external scripts like Zaraz.
• Reduces repetitive code
• Improves maintainability and usability in projects where shallow routing is problematic.

Cloudflare Zaraz Code for history.replaceState and history.pushState Overrides

// Override history.pushState
history.pushState = function() {
    try {
        // Remove all event listeners added by Zaraz
        zaraz._rl();
        // Clear all timeouts set by Zaraz
        zaraz._cts && zaraz._cts();
    } finally {
        // Call the original history.pushState method with the provided arguments
        History.prototype.pushState.apply(history, arguments);
        // Set a timeout to call zaraz.spaPageview after 100 milliseconds
        setTimeout(zaraz.spaPageview, 100);
    }
};

// Override history.replaceState
history.replaceState = function() {
    try {
        // Remove all event listeners added by Zaraz
        zaraz._rl();
        // Clear all timeouts set by Zaraz
        zaraz._cts && zaraz._cts();
    } finally {
        // Call the original history.replaceState method with the provided arguments
        History.prototype.replaceState.apply(history, arguments);
        // Set a timeout to call zaraz.spaPageview after 100 milliseconds
        setTimeout(zaraz.spaPageview, 100);
    }
};

Let me know if you'd like me to provide more context or discuss potential solutions!

[franky47]

Thanks for the report. nuqs@^1 did also patch the history methods, and so seems to work with your reproduction. If you are able in your project, can you try and install that version (1.20.0 is the latest in the ^1 line) and see if it works better? Note that there is no adapters in nuqs 1, so you'll have to remove it from your layout.tsx.

It might be possible to export the same enableHistorySync helper in Next.js that we need in React Router (and is optional in the React SPA adapter), to opt-in to patch the history methods and keep the same level of features (ie: not being stuck with shallow: false).

That being said, the issue should be raised with Zaraz and/or Next.js, because Zaraz breaks a core behaviour of Next.js, whether using nuqs or not.

A global option context provider was discussed at some point, but I feel like addressing the heart of the problem is more relevant. There may be other tools out there patching the history methods (I remember Plausible analytics did have some issues when Next.js broke their own history patch).

I really wish the browser had a native event for History changes (popstate doesn't trigger for replaceState/pushState unfortunately, just the Back/Forward buttons).

[nygmaaa]

Thanks for your reply, I downgraded to [email protected] and it works like a charm. Thank you!

enableHistorySync sounds like a plan, is it in the roadmap of nuqs@2?

That being said, the issue should be raised with Zaraz and/or Next.js, because Zaraz breaks a core behaviour of Next.js, whether using nuqs or not.

Indeed, my initial thought was that whether shallow routing or not makes no significant difference on my pages. That’s why a global option to opt-out shallow routing came to mind first.

[franky47]

enableHistorySync sounds like a plan, is it in the roadmap of nuqs@2?

It's not currently. Finding a solution to the root cause of the issue seems more relevant than adding a band-aid in nuqs. I'll run your repro again later to see if I can find a way to make those history overrides work (without nuqs involved). Could be a matter of loading a <script> before Next.js loads.