Type-Safe URL State Management in React With nuqs

Hello, everyone. My name is François Best. I'm a freelance software engineer from Grenoble in the French Alps. And so today I want to talk to you about this library that I made called nuqs. It is used by companies around the world like Sentry, Supabase, Vercel, Clerk, and many more. And it is a type-safe search params state manager for React. Its goal is to make URL states enjoyable in React, in all of React, all of those supported types.

What is URL state exactly? It's the idea of storing some of the state of our application into the search params or query string that key value store after the question mark part of the URL. Why would you want to do this? There is a wrong reason. If what you want to achieve is not losing the state updates that you did when you reload the page, that's not a good reason enough on its own to put it in the URL. Because reload resilience is more of a side effect, and you can achieve it with other means like local storage, for example.

The real reason you want to put states in the URL is that it gives your applications two superpowers. The first one is teleportation. By sharing a link with someone else, you teleport the memory representation of that state from your browser into theirs, so they can see the same thing as you do, pick up where you left off. This is also something 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. Your browser history is a way to travel back in time, to recall states from the past. If you use the browser's back forward button to time travel debug your state like an undo-redo, just be aware that you may break the back button. Be aware of that.

So how does it work in practice? If we see the URL as the boundary between the client and the server, it becomes this natural place for them to exchange data between each other. The client can attach some states on the request for the document that it's on, the server picks that up, uses it for data fetching, filtering, rendering 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 pass some state back to the client for it to handle client side. So we have this bi-directional communication link between the client and the server using only the URL text, which is pretty powerful. Now, there are some caveats 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 I will go through five different problems that you can encounter with URL state. The first one is that the URL has a size limit.

The practical limitation is not going to 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 10-stack table state, which one would you rather click on? The second one, exactly. Because first, it looks less scary, it is smaller, so it fits our criteria. But you can also understand what it's going to do just by reading it. It is a user interface. It is the first user interface that your users will see before they land on your application. So you want to design your links at least as well as your open graph images.

The second problem that we might have with this is that once users have shared links across the internet, they're out of your control. And if you want to introduce breaking changes in the search programs that you accept in your page, you will have to now run migrations against those URLs that come in. Because you don't want to break existing links. Cool URLs don't change, you want to honor the semantics of the links that have been shared in the past for as long as you can. And so, this can be done with migrations middleware and redirects to pass back to your application the result of the migrated URL.

Another problem that's not super well known is that browsers rate limit URL updates when you update them client-side, for security reasons. And nuqs solves this with a feature that I like to call time safety, which is decoupling of the UI. So you have instant optimistic local state updates for metrics like AMP and keeping your application responsive. And on the other side, throttling the URL updates at a rate that the browser can handle. You notice that they actually don't have the same rate. So it needs to adapt for this. And on top of this, you can add some debounce semantics in case you're only interested in the final state for high-frequency updates like text inputs or a slider, for example. Another problem that you can encounter is that by putting state in the URL, you create entry points into your application.

And so, the state machine of your frontend has to now be aware of these shortcuts that you can literally enter through. Because people don't just navigate through by clicking throughout your application. So you need to be aware of these things. And the final point is SEO. TLDR, you want to define a canonical representation for every page where you have search params so that search engine crawlers can index the right thing. And you can have search params in there, like the YouTube watch page, for example, has the video ID in the vsearch param.

All right. So now that we've seen some problems, let's have a look at some solutions. How does nuqs work? Well, let's do a demo. So, here I have the hello world of state management in React. The counter button. We've all seen this. I click this count. It increments. But that state is locked in space and time in this browser tab. How do we lift it out into the URL to make it shareable? We're going to replace use state with use query state from nuqs. And the first argument is not going to be a number. It's going to be the name of the key I want in the URL. Count.

And if I save this, you'll notice that my state has disappeared. My data type is now string or null. It is null if there is nothing in the URL. And by default, everything is a string. So we need to tell nuqs that we're working with a number here. We do that with a parser. Parse as integer. And so now my state type is number or null. The other thing to notice is that it is API compatible with use state. We have the value that's in the URL and a function to update it. This null, however, is annoying because it's breaking our logic here.

So we can make it non-nullable by passing a default value with default zero that will be returned when there is nothing in the URL. And now we've kept our button. And it works again. I can increment, copy it, send it to a friend or another tab. And I have teleported my state from one tab to another. Simple.

How does this work? Because this component actually would work in any React framework. So how does it work? Here I am in the nuqs.js app router. So if I go to my layout, root layout file, you will see that I have this nuqs adapter provider here that I import straight from the nuqs.js app router specified for it. And it tells nuqs how my framework works, how to read the URL using useSearch params in this case, and how to update it.

And how to update it is now why we need to look at the network tab. You'll see that if I click the button, the URL increments, but there is no network request being made. And why is that? Well, if we go back to our components, we notice that this is a client component that states existed in useState in memory just here at that before. And this is a static page. So we are not listening for search params on the server. There's no reason to go across the network for this. But still, we need to understand the two ways of updating the URL.

Our routers generally give us an API from useRouter, usesLatNavigation, useHistory, things like that. And that will generally send a network request to perform server-side rendering by using those search params on the server. But there is another method, the History API, which is built in the browser. It's not a Next.js or any framework thing. And this only updates the URL client side. This is something we also call shallow routing. And nuqs uses this by default, because we're guaranteed to have a client where we run those hooks. We're not necessarily guaranteed to have a server-side rendering process on the other side.

What happens if we do want to go across the network to do server-side rendering? So let's have a look at another demo. Right. Close this. Here, I have a list of albums with some filters that I can show you the code for. This is a server component page in Next.js that fetches the data from a database, renders these filters, and then the grid of albums. And so, we want to create a shareable UI for this. So, we're going to start declaring what we need. Nuqs uses a declarative approach. So, I'm going to create a new file next to my page called searchparams.ts.

And in here, I'm going to describe what I need in an object. So, searchparams. The keys in this object are going to be the keys in the URL. So, I'll have query. And the values are going to be the parsers for the types that I need. So, parse as string. I'm going to import it from nuqs server. That's a Next.js-specific thing just for use client directives purposes. I'll define a default value of empty string. Why not? And release.

That's a Next.js-specific thing just for use client directives purposes. I'll define a default value of empty string. Why not? And release. Yeah. Parse as integer. And we're not going to define a default value for this one because it doesn't really make sense.

What I have now is a descriptor object that I can reuse throughout my application. There are two places where I will need it. On the server to parse server side, the request that comes in, and on the client to connect to my UI.

So, let's start with the server. We're going to define what we call a loader function in nuqs. Const load filters equals create loader. And I'm going to pass it this search parameter descriptor object. And this function I can call with lots of different types of inputs. Here I'm using Next.js, but I could pass it the request in a remix or React router loader, for example.

Const filters equals load filters. Pass it the search params. Now, this search params prop is a promise. So, I need to await it here. I can also await the result. If you pass a promise to a loader, it gives you a promise to the parsed values. And I can pass this to my database.

And if we look at the data type, we see that it matches the schema that we defined before. I don't have a UI for this yet, but I can already use the URL bar as the input. So, if I do query Beatles, I have all the albums by the Beatles. Nice. Okay, let's connect our filters now. These are our client components. We need to wrap it in suspense.

But what we're going to do is we're going to need a hook in there. So, we're going to export a hook from our search params definition file. We're going to do exports const use filters. And we're going to forward this to use query states with an S this time, which deals with search params descriptor objects. And this I can now use in my filters component.

So, same API as you state value and a function to change it, use filters. The values is going to be an object with these two properties. And the state of data function is going to be set search params. Now when I uncomment these, React is going to complain that I'm going from uncontrolled to control. But look at what happens in the input when I save. Save this one. You see that it picked up the state from the URL because the URL is the source of truth. But now if you remember what I said about the button, you'll notice that if I type something here, nothing happens.

Why is that? Because we're still in this shallow mode, client only mode. And we need to tell nuqs that we want to go across the network. And so we do this with an option that I can define here. So that is co-located with the rest of my hook called shallow false. So when I save this, it picks up that thing, sends it through the network to the server. And obviously it doesn't do anything, but I can do beetles and 1967 beetles for sergeant Peppers. Nice.

So let's connect our clear button, mark clear button. We can set individual search params to the default value. But remember what I said about no, no means not in the URL. It also means clear from the URL when you write. So we can do this little shorthand of setting it to no. And an interesting thing is what happens if I have something unrelated in the URL, like foo equals bar in the middle. And I click clear. It keeps the rest of the URL as it is in the URL. And this is how nuqs scales. It composes different things, isolates them together and then resolves them when it's time to update the URL for you.

It composes different things, isolates them together and then resolves them when it's time to update the URL for you. So let's make this go away. And what else can we do now? Well, we still have a little problem in our code. If I type, say, love, you'll see that I have sent four network requests. One per character. It was just throttling. That's not great.

So what we want here is the final state. When I stop typing, what we want is debounce. So let's start by passing in some options here. So I can do it at a call site, options from nuqs. And I can spread those here. And here I can specify an option called limit URL updates of debounce. 250 milliseconds will do. If you're wondering what this debounce function does, it's just a constructor for a descriptor object that defines whether we debounce or not on the time in milliseconds. Nothing magical here. Syntactic sugar.

And what this gives us is now something that if I type beetles again, it only sends the request at the end with beetles. Cool. Except there's a little problem with this update now, because when I type something, you see that nothing happens. We don't have any feedback that something is going to happen. I have this little is loading prop here, which gives me a spinner on the input. And so let's connect this to a transition. Use transition from React. I have is pending start transition. I can connect is pending to here. And now I need to know where to fire this start transition. Nuqs has built-in support for it as an option, so I could pass it here. But it will only fire when the network is being sent across, the request is being sent across the network. You'll see that at the end, it spins just for a little bit.

What we want to show is that something will happen. We want to show this spinner for the whole duration of when I type, plus when the server has finished returning. What we can do is wrap our state of data function in start transition. I can do this here. And there is a little trick to the state of data function, it returns a promise that resolves when the URL has finished updating. So what we can do is async here, await that. And now this transition is going to last for the whole duration of the debounce queue, plus the time it takes the server to render.

So if I go for love again, you saw that love is a bit short, so Beatles, you see the spinner keeping going. There we go. The little problem that we have here now is that if I increase the debounce time, you'll see it. If I type love again, it takes one second to come back. But if I click clear, it also takes one second before it clears, because we've defined this debounce semantic globally for this hook. And so now all calls to the state of data function are debounced. That's not really what we want. We want to debounce when we type.

So I can move this option from the global level to the state of data function level and remove it from here. And now if I type love again, it takes one second. But when I clear, it's better. But there is another way to clear an input. If I type love and I select all and I press backspace, it also takes one second. That's not great, but this is easy to fix because we have the value that we are setting here. So we can choose when we are actually typing some values, we debounce. Otherwise, we do not. And so now if I go for love, one second, select all, backspace, instantly. Better. Declarative time safety. Let's add some favorites to these things. What are favorites? Any ideas? No? Links. Good old links that you can click. They preset your URL and the rest of your UI follows.

How are these made? They are hard-coded. That's not great. We want type safety for those, too. So let's go into our search params definition file and export a new helper, const getAlbumsLink. And here I'm going to use something that is not actually part of nuqs, createTypedLink. It's a utility that you can install into your application because it uses the type routes feature from Next.js. So I have these type-safe path names that I can connect to my set of search params. And now this function will be strongly bound to that path name with those search params. TypeSafeRouting.

So the way it's done internally, it uses a nuqs API called a serializer. It's the opposite of the loader. It generates an href string from a state of type, states. And it binds to this route type definition that is generated by my Next.js local config. Cool. So let's use that in our favorites. I'm going to replace those with this function, getAlbumsLink. And I only have to specify the search params here. I'm going to let AI do the rest. And this one. Thank you. Now, this has not changed anything in the output. We're still having the same thing, but at least it is type-safe. If I do a mistake, it will tell me. That's better. One thing that we can do with that is we have this query and release here in the URL. Those are variable names that make sense throughout the application. Those are for developers. They might be a bit verbose for the URLs.

Those are for developers. They might be a bit verbose for the URLs. So we can remap them to shorter keys with nuqs. We can use the URL keys feature for this. URL keys of that. And I can have these variable names being remapped to a shorter key. So I map query to queue, release year to year. And now I need to pass this mapping to my other exports. So here, there, and everywhere. And as you see, the thing resets because I introduced a breaking change here by renaming my keys. So be aware of your breaking changes. But now I have these short keys everywhere, and I have not changed anything else in my application. They all use these variable names, but short URL keys.

Cool. Last little thing I want to show you is how do we test this? How do we make sure this still works? I have this test file here which uses vtest to test two scenarios. We want to test that when we load a URL, our inputs have the right value. So I have this testing adapter that mocks everything that nuqs needs. And we can pass it an initial set of search params. And we make sure that our inputs pick up those right states. But we can also check against updates. So here I have an update spy function. That I can mount my UI, fill up some search, and then make sure that the optimistic state update happens. So those values already have the right... Those inputs already have the right values. We can make sure the spinner shows. And then after a given time, the URL updates correctly. Except that this fails somehow. Try again. This should fail. There we go.

This fails for a reason. Because I have first forgot to remove this to 250 milliseconds. My thing was expecting 250 milliseconds. But it also fails because it's expecting Metal, the query, to arrive first. And that's because I have actually a bug in there. That I debounced this first input. But I also need to debounce my release input. So I can pass this here. And now my test passes. That's better.

So we can test nuqs. It is possible. And it mocks everything you need for you. All right. Let's do a recap. So we saw that nuqs uses a declarative approach to search params. Both in terms of type safety and time safety. And it scales by composition. So declaration and composition are the core tenets of React. And nuqs uses the same approach to scale your application. And it is not particularly opinionated to where you define those definitions. You can do it next to the page as I did. Or you can do it next to the components. And each component exports its own behaviors. And then you can compose them together at the page level. And it is incrementally adoptable. You can start with one useQueryState. And then progressively enhance with other definitions. UseQueryStates. Deriving types.

And all these kinds of things. And so to conclude, I will say that the URL state pattern is a powerful one. And with great power comes great responsibility. So my last advice before we leave would be... Never underestimate query strings. Thank you.

First questions are going to be pouring in. But we'll start with the first one. Is it open source? And what has it been like maintaining open source, if so? So yes, it is open source. We have almost 10,000 stars on GitHub. And we just passed a million weekly downloads. So yeah, it's doing well.

How has it been maintaining it? It's been a wild ride, that's for sure. Because I do this on my spare time. I have a freelance business. And I do this on evenings and weekends. I would love to be able to spend more time doing it full time. But over the time, it's been mostly me working on it.

And now a lot of people are starting contributing to it. Thank you, Dominic. He's been contributing a lot to it. And it's really good because it now shifts the role from implementing to orchestration. And it's a different dynamic. But it's really interesting to see how people bring new ideas to the project, and how to compose them with a global vision on where we want to go with this. Thank you for that.

Another question has come in. Can you integrate with validation schemas like Zod? So, yes, with adapters, with transforming the validation. The validation problem is something that a lot of people have asked. Do you support Zod natively in Nuxt? And just before version 4.1 of Zod, the answer was no. Because validation libraries like Zod, or anything standard schema based, lack the reverse transform of going back from a data type to a string. If it's something simple like a number or a string itself, that's not usually a problem.

If you start integrating it with objects, like a sort option, like you have the key you sort against, and the direction. You want to sort these into one thing. And you generate an object out of that. You need the reverse transform to reencode that into the URL when you write to it. And so validation libraries could give you one way transform, but not the other. Zod 4.1 came out with Codex, which allow you to do this bidirectional transform between two data types, including serialization and deserialization.

And so now we can support these things, which do both validation and SERD, serialization deserialization. So there are others that do this, like effect schema does that too. And yeah, that would be it's possible to use these as long as they have the bidirectional flow. Nice. Yeah. Another one, how would you handle scenario where you wanted to delay the application of your query? For example, if your filters are in a modal or a drawer and you want them to apply all at once. So what you can do, it's decouple the URL state, the URL updates, and the local state updates are decoupled. And you have these declarative time semantics that you can add. So throttle or debounce. And one trick is to set these values to infinity. It will never update the URL until you do another update with the standard throttling rate.

And that will just push everything that's currently in memory in your local states into the URL all at once. So you can do a bit like a form. Essentially, what you're trying to do with this kind of UI is a form. You try to put states locally in your thing. And then at the end, you press submit and it sends everything. Basic functionality of forms was always to send the queries in, like the values in the query string, before we had client-side reactivity.

So either use a form, if that's what you're trying to achieve. Or if you really want to do this, you can bypass the URL update by setting it to infinity. And does nuqs handle compression of query parameters? It does not by default, but you very much can create a custom parser. So we have a lot of built-in parsers, but you can also create your own. And so you can definitely create... Some people have done that, actually. Creating a custom parser that would compress on write and decompress on read.

And since parsers are composable, you could have some sort of middleware parser that does this kind of compression and pipe it into another parser that deals with properly transforming into a data type that your application needs, like an object or a number, something bigger, I suppose, because generally compression will be about storing big values in the URL. The main thing is to remember that it is limited in space. So don't try and put too much in there. Cool. And are there synergies with TanStack?

Router. Router. Yeah. TanStack Router uses a very similar approach in terms... They do it a bit better in terms of type safety because they have more control over the whole routing system. They define search programs behavior at the page level, and that gives them the ability to do type-safe linking built in the browser. You just have to specify which routes you want to link to, and you have the set of search programs that matches the schema that you defined. This is amazing. That works really well. The thing is, nuqs uses a very similar approach, but it has per-key serialization customization. We do support TanStack Router in terms of loading those hooks. So mainly for people who have TanStack Router slash start applications to be able to load components that use nuqs into their applications, I would still recommend you to use the TanStack Router APIs for search programs management. If you're building with TanStack Router, you'll have probably a better experience with this. And yeah, it is similar in many ways, and they do compose together. I need to work on making it work a bit better.

Okay, nice. Yeah. All right. And does nuqs prevent scripts injection attacks in the query for our app? If you follow me on Twitter, you'll notice that two days ago I actually did a script injection attack myself to show that it was possible, and don't do that. So you don't want to eval anything in your parser, that would be not great. It doesn't do anything by default on its own, but for example, a great example of this is if you want to pass a redirect, I show this in the URL clients and server data exchange. If you want to pass a redirect going into your clients, you want to make sure you do pass it against the origin, and or it starts with a slash, things like that. So it prevents open redirects into our application. So nuqs doesn't give you this by default, but you can create a parser that does exactly that, like safe from or something like that.

And does nuqs play nicely with client-side global state management libraries like Zustand, Redux? Zustand, I have an example to make it work with Zustand. Like if you want, for example, in a Zustand function to read from the URL, you can actually use the loader for this. It's not limited to the server side. You can use loaders pretty much everywhere for this one time parsing of the URL. So you do a loader.location.search, for example, and that will give you the current state that's in the URL into your Zustand function. But yeah, for example, Jotai has a built-in system for synchronizing to the URL.

But yeah, for example, Jotai has a built-in system for synchronizing to the URL. Redux I'm not sure, but Redux is basically essentially the same thing as Zustand in terms of the data flow. So that would work essentially the same way.

And before we close, because of timing, can you quickly answer, can it handle arrays? Yes, it can in many ways, thanks to Dominic. We could handle arrays in a compact form. So you have one key and then multiple values separated by a separate character, like a comma, for example.

But recently, thanks to Dominic's contribution, we can now have the repeat of keys. So they have foo equals bar and foo equals egg, and then you have bar egg into an array. So now we can do both. You can choose which method you want to do. Cool. We're out of time. Thank you so much. Thank you very much. And if you want to speak to him, he's in the Q&A section.