App router support - research thread

[franky47]

Note

This discussion turned into a kind of sounding board / raw brain dump. Sorry about the mess! 😅

Context: discussion started with Pierre Spring on Mastodon.

After merging #328 which adds support for the app router in Next.js 13+, some performance issues appear there.

Any high-frequency updates (eg: binding a query state to a text input and typing characters, or to a slider and moving it) cause a lot of lag on the UI. This requires some further investigation, but it opens the question of how this hook is being used in the wild.

For UIs where the URL is not really the source of truth, but a way to share state with others, or keep it in case of reloads, a throttling approach would make sense. The internal state would be the source of truth, and periodically be persisted in the URL. On mount, it would read the initial state value from the URL, but not react to changes.

[franky47]

An initial test shows that the app router now performs a network request every time there is a querystring change.

app-router-lag.mov

It kind of makes sense to let server components handle it, which wasn't the case in the pages router (only pathname changes triggered server-side data fetching code).

Unfortunately, it makes the hook unusable as-is (dependency on network can be exacerbated with throttling network requests in devtools). Any attempt at throttling or debouncing won't really solve the problem, as it is now dependent on network conditions. In the pages router, the hook could even work offline for a truly client-first experience, which won't be possible now.

Some alternatives to consider:

• Updating the query string without going through the router, and sync hooks via external means. This is to avoid the waterfall of network requests, but feels hacky. Edit: navigation without invoking the router does a hard page load, which yields hydration errors. Not a solution.
• Having two state update methods: one that updates an internal state, and one that commits to the URL. For inputs, those would be bound respectively to onInput and onChange. Edit: having two APIs is very confusing, and discrepancies between onInput and onChange behaviour across browsers makes it unreliable.

Related Next.js issues:

• (Shallow routing) updating search params causes server code to rerun. vercel/next.js#49668

[franky47]

After testing a lot of potential ways to fix this, the following comment helped gain some reactivity.

Using the HTML history API allows changing the URL without triggering navigation (ie: without hitting the server and re-rendering and whatnot). It's ideal for client-only updates, when paired with an internal state per hook and a way to keep them all in sync (either via some event listener on history changes, or via a dedicated event emitter).

There are a couple of issues with this approach though (similar to what we had in the pages router):

Reloading the page gives a hydration error, which is to be expected: the server renders all hooks with a null/defaultValue, but the query string is read on hydration and returns some other value. The solution in the pages router was to wrap any components that used a query state into some form of loader that doesn't render anything on the server NOR on the first hydration render on the client (it could render a spinner or some sort of skeleton UI).

Note that server pages now have access to the query string as props, but there's not currently a way to access it via a hook on an SSR context. With the absence of React Context on the server, this would resort to props drilling, which is a no-go.

Edit: useSearchParams actually contains the querystring on server renders, so we can now use this to get a correct initial query value and not have any hydration issues! 🎉

The one issue left is that of syncing the internal state of all hooks with the same key. The idea would be that the URL be the source of truth, and the individual internal states would sync up to it. This is wasteful as it requires re-parsing for every hook instance. Instead, an event emitter pattern can be used to sync the parsed states directly, and have only the writer hook update the URL. Some potential issues with this approach include:

• Data races between two hooks setting different values
• Non-reactivity to external URL changes (eg: a Link setting the query, though that would probably trigger a server render or an update of the useSearchParams, will test).

Another issue is that the history API is rate-limited by browsers, so maybe some form of throttling URL updates would be welcome. The UI would be just as reactive as we'd still be syncing the states as fast as possible.

[franky47]

The last hurdle seems to be a bug with Next.js' router, which doesn't trigger a page-wide render when clicking a <Link> that has the same query params as the initial server render, even if there are more added afterwards, which then don't get cleared. Kinda leaning towards calling that an acceptable limitation and moving on.

[caillou]

This could almost be considered an expected behavior ;)

[franky47]

True, but the fact that the state doesn't follow the URL after clicking a link feels like a bug to me.

[franky47]

I have a potential hack that fixes that: by patching window.history.pushState/replaceState, which the Next router uses for Links and imperative router calls, I can trigger a state sync. The unused second parameter can also be used as a marker to tell the patch whether or not to perform the sync, as it's not necessary to re-render every key when going through the regular useQueryState API.

Idea stolen from react-use, which monkey-patches the location and history APIs to gain reactivity.

WDYT? 👍 / 👎

[franky47]

2023-09-04 update: while trying to solve a limitation of previous versions where a high volume of query updates would trigger a security error in browsers, I ended up removing another limitation: batched updates for useQueryState.

In previous versions using the pages router, updates to a query had to be awaited so the URL had time to change before another could be applied onto that (otherwise the latter would take precedence).

Since we're no longer bound to the Next.js router for URL updates, nor to the URL for the absolute source of truth, we can put a queue between the hook and actual updates to the URL, that gets throttled to avoid security errors and that runs one tick after the React event loop to allow batching. 🎉

This makes the whole point of maintaining two implementations (useQueryState for a single query key and useQueryStates for multiple related queries) kind of pointless: use one hook per query, update them in the same tick and they'll move together. Since React also collects and queues state updates within the same tick before triggering a render, it should also mean a single render pass for multiple query updates (TBC).

The only point where useQueryStates might make sense is if the query map is dynamic. Because we can't have a variable number of hooks in React, this offers an escape hatch, although it seems fairly hacky and if one has such a use-case, I'd love to know more about what they're doing. There may be alternatives like moving individual useQueryState hooks into components that themselves get rendered conditionally. Edit: there are valid uses in the wild where tying params together in an update makes sense. A classic example is map controls (lat + lng + zoom).

So I'm leaning into fitting it all in a v2.0.0 with a breaking change, that includes the following:

• Unified implementation (no need to use different imports for app or pages router). Easier to maintain, easier to test, lighter to ship.
• Dropping useQueryStates altogether.
• Dropping support for Next.js router transition options:
  • scroll is false by default (no scrolling back to top of the page when changing a query)
  • shallow mode by default (no calls to the server on query change).

For shallow mode, and especially in server components that can now access the query string server-side, it may be useful to have a way to commit a query update to the server for remote processing. With strategies like a deferred update queue, that may be a problem as the URL/history entry won't be available right after a call to the hook's update method. so maybe it should still be something to propose as a param, eg:

const [text, setText] = useQueryString('text')

const onSubmit = () => {
  setText('foo', { server: true })
}

For other purposes, accessing the updated URL can be done with the same deferring technique:

const [a, setA = useQueryString('a')
const [b, setB = useQueryString('b')

const onSubmit = () => {
  setA('foo')
  setB('bar')
  console.log(window.location.search) // ''
  setTimeout(() => console.log(window.location.search), 0) // ?a=foo&b=bar
}

We could also keep the Promise-based API by awaiting the next tick, so that async code can still work as it used to.

[franky47]

🚀 PSA: 1.8.0-beta.6 has been published, and includes (for the app router only, no changes to the pages router yet):

• Individual internal states per hook site for fast updates
• A deferred, throttled queue for updating the URL query string, which allows batching and exposes a Promise-based API to know when the URL has been updated (and what it contains)
• A sync system between hooks and with external navigation, from <Link> and imperative calls to the Next.js router
• No more network calls when updating queries (shallow by default)
• No more scroll to top when updating queries (this is kind of a breaking change).
• Better interoperability between individual useQueryState hooks and the same keys aggregated in a useQueryStates, with batching support

Initial tests are very promising, performance is identical to what we could have with standard useState hooks. The one caveat I have not yet found a solution for (don't even know if there is one) is Safari's incredibly low rate limits (100 query updates in a 30s rolling window) when binding queries to high-frequency inputs (even typing comfortably in a text inputs breaks the limit).

Note that for the pages router, under Next.js 13.4+ it's possible to use the app router from 'next/navigation', so importing next-usequerystate/app should work, with some caveats:

• The API is a bit different (options are gone)
• It requires some special handling of the first client render to avoid hydration errors, as there are no server-side queries to pre-render there

I'll test the compatibility with the pages router a bit more, and if things look good I'll expose only a single implementation for both. In any case, this will end up as a breaking change for various reasons (behavioural and API), so it will eventually end up in a v2.0.0.

[caillou]

These are great news!

The one caveat I have not yet found a solution for (don't even know if there is one) is Safari's incredibly low rate limits (100 query updates in a 30s rolling window) when binding queries to high-frequency inputs (even typing comfortably in a text inputs breaks the limit).

The average person types between between 190 and 200 characters per minute. Let's cross our fingers and hope for the best.

While we could add an option to throttle the updates to the URL, this seems like a premature optimisation. And this could easily be in a wrapper hook.

All in all, this looks very promising and is by far better than my initial implementation that used useSearchParams() with a throttled const router = useRouter(); router.replace(). Thank you so much for all the work that went into this!

One question: when using useSearchParams, server side page rendering is deopted into client-side rendering. I assume there is no way around this issue, right?

[franky47]

One question: when using useSearchParams, server side page rendering is deopted into client-side rendering. I assume there is no way around this issue, right?

The only way is to follow Next's guidelines and place the query hooks as far deep into the render tree as possible (and in a client component), so the rest of the page can remain server-rendered.

Since they are all synced by key, prop drilling should not be necessary: add copies of the hooks here and there, even with partial access (eg: write in one component and read from another).

[tacomanator]

I'm trying out the beta branch (1.8.0-beta.9) but finding that hydration is not working on page navigated to via link as in:

function Page1() {
  return <Link href={`/page2?foo=bar`}>Page2</Link>;
}

function Page2() {
  const [foo] = useQueryState("foo");
  return <p>{foo}</p>; // starts and stays null (not hydrated) until page refreshed
}

The Is this expected? (only tested in app folder).

[tacomanator]

I realized that my example only works from pages folder.

In the app folder, searchParams is defined from the outset.

I can see the merits of a promise, but perhaps a reason for a third parameter approach is to work the same in pages/ and app/.

[franky47]

That could indeed be a way to know in which router the hook is added. I did a quick prototype last night that seemed to work, but was very hacky and got stuck in invalid states too easily, will have to give this more though.

Thanks for your help, it's very much appreciated! 🙏

[franky47]

Some findings:

There can be a variable number of RSC requests fired from a non-shallow query update in the app directory, based on the app structure. There will be at least one for the root, and one per boundary, which I guess can hydrate at different times. This is making a single loading state impractical to compute or actually use. Moreover, Next caches the result of RSC calls and doesn't send a request when navigating back to a query value it has already cached.

FYI, I haven't been able to reproduce a case where useSearchParams returns null, neither in the pages nor the app directories, and with any combination of the two (the Next.js docs state that it might happen when they are both present in the project, for migration reasons).

[tacomanator]

I could investigate that, but either way it sounds like the loading parameter might be difficult. I haven't given it much thought yet, but maybe there is a viable alternative. URLSearchParams has a has() method. Could the result of that be used as the third parameter instead? true/false or undefined if not yet known?

[franky47]

That would be much easier to do, yes.

It would only give the info of whether the query is present in the URL, which in turns gives some context to the state value: is it equal to the default because the query key is not in the URL, or is it because the query is explicitly set to the default in the URL.

In any case, this is a pages router specific thing, that occurs when the page is static, and for which a hydration test is required anyway, because the state value for queries can't be known at build time.

In the app router, a similar setup is required on static pages by wrapping the client code in a <Suspense> boundary, otherwise the whole page gets demoted to client-side rendering (potentially shipping a heavier bundle to the client).

[tacomanator]

Another possible issue, perhaps related to the change to parsers. It seems like parseAsJson could be double encoding the value? It is working in the sense that the value is provided correctly, but the URL is maybe unnecessarily long?

const [foo, setFoo] = useQueryState("foo", parseAsJson<Object>>());
setFoo({}) //  expecting: foo=%7B%7D, current actual: foo=%257B%257D

[franky47]

Good catch, thanks. Looks like URLSearchParams.toString() already calls encodeURIComponent internally, so there's no need to pre-encode it in the parsers. I got fooled by Firefox's URL bar displaying decoded safe characters:

[franky47]

There is however the need to encode items of an array (parseArrayOf), otherwise items containing the separator may cause incorrect split of the query items.

[franky47]

There's an interesting behaviour with URLSearchParams.toString, that may seem like a bug for when using this hook, but I believe is a feature.

In the compound parsers demo, clicking "set code to {}" shows (in Firefox) a url of ?code={}. Pushing an empty object on the array query gives ?code={}&array=%257B%257D, still correct, but pushing an array on the array query re-encodes the empty object in the code query:

?code=%7B%7D&array=%257B%257D%2C%255B1%252C2%252C3%255D

As everything parses fine, I'd be willing to call this a protective feature and not worry about it too much.

Edit: Chrome and Safari are more conservative and will set the first empty object to ?code=%7B%7D.
I guess it's a Firefox-specific thing to render the URL more nicely for the user.

[tordans]

@franky47 I was looking for a solution to this issue. I am migrating a project to BlitzJS (NextJS). Right now the URLs look nice (but long…) like below. But using next-usequerystate they are now all escaped and just don't look very nice :)

Update: I moved this comment into a request at #355

[Arctomachine]

Not sure if this is right place to say this, but something is not working right in latest version of next (14.0.2-canary.8 as of moment). Now it completely resets state multiple times. First time immediately after setting state, subsequent times on page scroll. It resets url to default (removes search query) and thus components rerender to initial state too.

My workflow in project is as following

[franky47]

Sounds like something broke on the Next.js side, I'll take a look but I doubt I can keep up with their canary release cycle (multiple times a day). Though I saw your comment on the cache issue so I can understand the itch of getting error-free builds (I'm stuck on 13.4.12 for the same reason).

Do you have a reproduction somewhere? Feel free to open an issue.

[Arctomachine]

I am checking what might have caused it in my particular project. So far I made it work by disabling prefetch on links in wrapper/consumer component. Could be bug in my code, need to further check it

[Arctomachine]

So yes, prefetch is cause of this bug. Was able to reproduce it in new project, will upload soon

[Arctomachine]

#388 made issue with reproduction