Known issues & solutions / Version compatibility table

[franky47]

Opening a dedicated issue where I can post more details about known compatibility issues with Next.js features. Browse through the list of comments below to find matches with your Next.js version.

As a reminder, here's the compatibility list as stated in the README:

Next.js version	Supported next-usequerystate version
>=14.2.0	nuqs@latest
>=14.0.4 && <= 14.1.4	nuqs@^1
14.0.3	nuqs@^1, with the windowHistorySupport experimental flag, see below
14.0.2	Not compatible, see below
>= 13.1 && <= 14.0.1	nuqs@^1
< 13.1	next-usequerystate@1.7.3

Why this thread?

Since this library is tightly tied to the Next.js router internals, it tends to uncover bugs. Whenever possible, I'll try to propose fixes to the Next.js core when those issues arise.

Because this software is released with a different lifecycle than Next.js, there are bound to be compatibility issues with Next.js fixing a routing bug, and this library adapting. One case of this was the introduction of shallow routing via the windowHistorySupport experimental flag, which broke a few things in next@14.0.3.

This library is continuously tested against every new Next.js release, including canaries. See the action runs for more details. I explain how it's done on my blog.

This thread is an internal log of known issues for which there is a fix path, if you encounter something that doesn't look right, please open a dedicated issue with as much detail about your usage, that would help a lot, thanks!

[franky47]

Versions concerned

• Next.js: 14.0.2
• next-usequerystate: >= 1.8.0

Conditions

• Using the app router
• Having <Link> components rendered in a page where useQueryState is being used.

Issue

Hovering a <Link> component resets search params set with useQueryState(s). See issue #388.

Solution

Upgrade to Next.js 14.0.4.

Context

In 14.0.2-canary.7, Next.js introduced a way to process internal app router state changes asynchronously. This change triggered a side-effect to run on every update, which includes prefetch when <Link> components are mounted or hovered. This side-effect replaced the URL with its internal known URL. Because there is no way in 14.0.2 to do shallow routing, the app router isn't aware of the updates made by useQueryState, and so loses changes it made.

We added a fix in Next.js in PR #58297, which landed in 14.0.3.

[franky47]

Versions concerned

• Next.js 14.0.3
• next-usequerystate: ^1.12.0

Conditions

• Using the app router
• Not using the windowHistorySupport experimental flag

Issue

When navigating to a page via a <Link> component and including search params (eg: <Link href="/foo?q=search">), those params are not loaded. See #416.

Solutions

Upgrade Next.js to 14.0.4, or enable the windowHistorySupport experimental flag on 14.0.3.

Context

The windowHistorySupport experimental flag was added in next@14.0.3-canary-6. We added support for it in next-usequerystate@1.12.0. However, the baseline (without the flag on) had an issue in how the window.history methods were patched, which made next-usequerystate unaware of external navigation via <Link> components (or router calls).

A fix was added by the Next.js team in vercel/next.js#58861, which landed in 14.0.4.

[franky47]

Versions concerned

• Next.js 14.0.3 or 14.0.4 with the windowHistorySupport flag turned on, or Next.js 14.1.0
• next-usequerystate: ^1.8.0

Conditions

• Using the app router
• Using anchor tags with fragment URLs: <a href="#section">

Issue

Clicking an <a href="#section"> link (eg: in a Table of Contents nav to jump to a section), then setting a query state, throws an error:

TypeError: window.history.state is null

Note: the error contains a message about rate-limiting, which is misleading and due to the try/catch mechanism not discriminating between different types of errors when setting a state.

Solutions

Upgrade Next.js to 14.1.1-canary.55 or later

Context

This issue is not related to nuqs, but a bug in the Next.js app router in handling the intersection of anchor fragment links and shallow routing. It also happens when calling window.history.replaceState(...) directly, which nuqs does.

The issue was raised in #498, and fixed in Next.js by vercel/next.js#62098, released in 14.1.1-canary.55.