Type-safe URL state in Next.js with nuqs

[Music] Hello, NextJ. JS Con. I'm France. I'm a freelance software engineer from Grenobyl in the French Alps. And I'm here today because 5 years ago, I built a little react to React hook for my NextJS applications, which has since then grown into an open source project with about a million weekly downloads and used by companies around the world like Sentry, Superbase, Versel, and many more. This project is called Nux and it is a type- safe search params state

manager for React. Its goal is to make URL state enjoyable in React. So what is URL state? It's the idea of storing some of the state of our applications in the search params or query string or query params really if you must uh part of the URL that's key value store uh after the question mark. So why would we want to do this? There is a wrong reason that is if you don't want to lose the state updates that you did when you reload the page. It's not a good reason enough on its own to put it in the URL because

reload resilience is more of a side effect that you can achieve with other means like local storage for example. The real reason you want to put state in the URL is that it gives your applications two superpowers. The first one is teleportation. By sharing the link with someone, you share the memory representation of that state from your browser into theirs so that they can see the same thing as you do. Pick up where you left off. This is what we call deep linking. The second superpower is time travel. A bookmark is a way to send a link forward in time to

your future self. And your browser history is a way to navigate back through time to recall state from the past. You can also use the browser's back and forward buttons, a bit like an undo, redo feature, uh to time travel debug your states. Just be aware that you might break the back button in doing so. So be aware. So how does this work in practice? Well, if we see the URL as the boundary between the client and the server, it becomes this natural place where they can exchange data between them. The client can attach some state

on the URL of the document that it's on and the server picks that up, uses it for data fetching, filtering, returning custom content. Nothing new about this part. This is how the web has been working forever. The main difference is that now we have a client that can react to changes in the URL and so the server can also reply using the same system with a redirect. It can tell the client go there and I will attach some state for you to pick up on the client side to render your logic with. So we now have this birectional communications link between the clients and the server using

only the URL. Not a request response bodies, not an API endpoint, just the URL text itself. And that's pretty powerful. So there are some drawbacks to this approach. And I think as good engineers, it's important that we know the limitations of the systems that we're working with. So let's dive into this Eural state iceberg uh problem and see what dangers it might hive uh under the waterline for us. The first one is that the UL has a size limit. Servers are generally not going

to be the bottleneck here. But the transport the way you share links with others might be for example signal and WhatsApp will stop rendering huge links as clickable. Some other platforms they may decide not to send a message or may truncate your links breaking them in the process which is not good. But the main limitation will not be a technical one. It is a social one. It is that of us humans because we don't like long links. For example, between these two links which are semantically equivalent. They both represent a tan stack table state. Which one would you rather click on?

Yeah, the first one is scary. It's got URL encoded JSON and B 64 in there. The second one is much shorter, so it fits our criteria, but it is also understandable. You can read it and know what it's going to do. It acts a bit like a textbased user interface, and that's because it's exactly what it is. The URL is the first piece of UI that your users will see even before they click on it and land on your application. So, you want to design it at least as well as your open graph images. Now your users have shared links across the internet and from the standpoint of