Stop Writing Your Routes

So yeah, my name is Eduardo. Good morning, London. I'm happy to be here another year. So as a core team member, but also as a developer and an open source lover, I've been doing a lot of development of libraries, almost for seven years, I think. So not only PNEA and vue Router, but also some other libraries that are just adjacent to vue itself. And I have been spending quite a lot of time thinking about how do we design the APIs for these libraries. Sometimes messing up, making mistakes, sometimes improving them afterwards, of course. But the bottom line is designing APIs is really hard. And I think it comes without saying that this is one of the biggest challenges of any open source library. Because you have to factor a lot of, no, sorry, you have to take into account a lot of different factors from how does these api changes, wait, sorry, I need to change the thing. This is going to be painful. So you have to take into account a lot of different factors from, wait, my software broke here. And I think, how am I going to do? Okay, I have to do everything by heart. I'm not having any notes when you, we're supposed to have notes, very difficult. So you have to factor a lot of different things into account. You have to factor the users you have, are you building a new api, are you not building a new api? And how the api feels to users. Because at the end, an api being good or bad is very subjective. And I'm going to show you why. So one of the things that I feel is very important to a good api is to make errors hard to make. Now it might be obvious to some and completely new to others. But if you use a library where making errors is actually easy, it makes you feel dumb. Now nobody likes to feel dumb when they're using something, are they? So it's definitely a big factor in my opinion of how an api can be good or not. Another big thing is avoiding context switch. Now, when we think about APIs, we first think about the code we need to write. But if the actual api goes beyond the code we write, it's not only the files, the folder that we have, but we can actually think about many other things that are part of the api. Because when we write code, when we develop a program, we're not only writing code itself. And then we have to cut it for different user experiences. Now this is very vague, to be honest. But it's not the same to write a V1 of an api so you only have new users than writing a V2 of an api where you have existing users that are used to something. Also you have to think about what language you're writing for. It's not the same writing an api in Java or rust than in javascript or typescript where things are evolving very quick. And I like to refer to this little joke, the digital learning curve. So the thing is, our experience when learning something, which is also part of an api, the learning process, is different. And it's subjective. So the joke here is very simple, actually. You have the time horizontally and then how much you can do with a tool. So as you can see, Notepad, you can use it very quickly and you're not very efficient. Then you have Pico, which is just a terminal-based tool. And you can do a little bit more things. Then you have Visual Studio, which you learn a lot of shortcuts, I think. And I believe the joke is that then you start digging too much into the IDE and you spend too much doing things and then you become less productive. And then you have Veeam or Nveam, which basically you need to learn a lot before even being able to use it at all. But then you're very productive. And then you have Emacs and Spacemax, which bend time and space, I think, because there is no way to do that in math. And so I'm going to use this as a base for what I call api ergonomics. Now api ergonomics, I define it as how often do you use a feature? Feature being a very vague and abstract concept, OK? And how often or how easy it is for you to guess how to use that feature? Have you used it before or not? You have to take into account all of these things. Now you could imagine this is something linear. Of course, it's not. And it's definitely not the goal of having this kind of api ergonomics being linear. In reality, when I think it's better, well, of course, the best case scenario is having something that goes like that. But as you can imagine, that's really not possible in life, right? So we have to have some trade-offs here. And I think this is something, I mean, this graph, this ergonomic line makes more sense. And it's actually good. Now, if we compare it to the other one, linear, we can see that we're going to spend a lot of time doing the tasks that are easy to do, easy to guess. So this makes us feel smarter, because we can figure out the things by ourselves. So in terms of the experience we are developing in our library, it's much more interesting. On the other hand, anything that is quite complex, an edge case, things that you don't do that often, maybe you do one project twice, so maybe once a year or less, those are going to require more work. Maybe using different APIs, different options, combining multiple things on the library itself to make things work. You don't have one option, like in Nuxt, where you just do ssr true and you have ssr, where you do just view, right? You have to set up the V server, you have to set up many things. Now, I'm not saying Nuxt here is bad, quite the opposite, but I think there is a trade-off here to be found, and that if we make common features easy to achieve and easy to remember, we are gaining a lot at the end of the day. So today, I want to explore this path by erasing an api. And I really mean erasing, so this is not a breaking change, we're not deleting, okay? We're not removing, we're erasing. And I want to show it with ViewRouter as an example. And I want to focus on three things. I want to keep things together, so this is to reduce the context switch. I want to reduce repetition, so just to iterate faster, to be able to write more in less time. And I want to improve the development experience by making errors harder to make or easier to spot both things at the same time. Now, I think the routing or the router is a good place to do that, because the routing itself is widely misunderstood. And honestly, I don't blame anybody who doesn't really understand that well, routing, because it's the land for weird, ever-changing APIs on the browser. Like, do we use hash? So we used to do hash URLs, now we don't anymore, it's bad for seo. And then we have, because of that, multiple ways of parsing the URLs, which are totally valid and both work, and maybe you can even use both at the same time. By the way, they don't even have the URL in their api names, spoosh state, if you have history, but still. And then you have multiple ways of parsing it, like location.href, path, hash, and then the URL constructor will have URL search params. We have different events, and we even have upcomings APIs, which, as you can imagine, is not supported by all browsers, like Safari doesn't have a word on these api, which have been on an ongoing discussion for two years already. So we don't even know where to go. At least we don't have Intern Explorer anymore, but still. So on top of that, it's where a lot of the different things, or your application, come together, the routing. So you have state on the URL, you have the UI with transitions or animations that can happen between the pages, and then we have the model, like with data fetching, usually integrate that with the routing. And we have a ton of vocabulary, okay? And this might look like nothing, but when you have to remember the correct word when you're searching the documentation, it makes a big difference, because you cannot find the actual help in the documentation, so it becomes very frustrating. And on top of that, we have some error-prone behavior. For example, you define routes this way, having a path, a name, and then you can push with a name, and you can push with a string. But what was it before? Was the slash about? Was about? And you're not gonna get any error when you're writing this code until you go to the browser, so you context switch, and you see the error on the console saying, hey, there is no route named slash about. And it doesn't even tell you if there is another route named about. So can we simplify all of this? Of course, I wouldn't be speaking here if we cannot simplify this. And I want to focus on one very simple part of the routing, which is creating route, is the beginning of any SBA application. Now when you create a route, you usually create a file. This is something that we can merge together, and I think this is going to be familiar to a lot of you. And we are kind of erasing the creating the route, creating the object, the route record. The problem that comes before is we still need to configure the routes, but we're no longer writing the configuration. So how do we handle that? So I want to do a little quick show of hands. Who has used file-based routing before? Okay, almost everybody. Well, there is a big difference in both sides. More than half of the people here. So file-based routing is what allows you to define these routes, or even the route altogether, the router, sorry, altogether, by just having a folder structure. Now this is what Nuxt does, it completely erases the router creation. And I want to show you something similar, and I want to advocate for it a little bit more. So the idea and the key point here is we need a way to reduce the code repetition, which is what's happening here, without compromising the flexibility, which is being able to configure the routes. So when we have file-based routing, what we have, and what's very important, is that we have one-on-one predictable mapping. So we know, and we have a few rules that we maybe learn once. We know that index.view, like index.html, just become a slash at the end. And we know that if we have the brackets, it becomes a parm. And the good thing is that because this is sitting right next to you on your files, on your editor, you see this every day. So you don't really need to learn this multiple times. Okay, you learn it once, and then it's on your head, it's there. And because we have a one-on-one mapping, we can let all the tools generate the glue code. So we can write the interesting part only, ideally. Now this includes the route records and the imports, which is kind of boilerplate. But also we can have types that we could write manually, but we're going to generate them ourselves so they are always correct. And also other route meta and other things that go beyond that. So the idea here is we want to get an error if we write something like this. We don't want the classic typescript error when it says string is not assignable to type A, then you have three dots that you cannot even click, and then you go something like never is not assignable to string, and you don't even know what happened in between. You want, ideally, a precise error that tells you, hey, this object is missing the ID property, right? This name does not exist. This condition is not possible. So these are type string errors, okay? These param other does not exist for this route because we checked that the name is ID, so the shape of the param is an object with an ID. And so initially I wanted to do this with runtime types, which it's a very interesting feature of typescript. So you have what we call literal strings that we can actually parse, and we can transform into objects, into real types. These all work, okay? And I did, so the good thing is that you just need to take your routes array, you put these as const at the end, and then you can generate an object that contains all the params for every single name route. Now the problem is that this is really slow, and it took me some time to test because when I started doing it, you start with a few routes, but then when I get to 50, I realized that I achieved nothing but just crashing typescript server, which can be an achievement in itself, but it's not what I want for my day-to-day life in development. And on top of that, I have to say this is the most unreadable code I've written in my whole life. And I've written a lot of languages, and C, and Prologue, if you know this language. So I've written unreadable code a lot of different times, but nothing compares to this code. And I did try very hard to make some of the things readable, apart from the one-letter generics, which is just part of LifeScript life. And I'm not really ashamed, it goes even worse, okay? But I invite you to just check the link and witness the Turing-complete typescript magic here. And I'm not gonna dive into the types, of course, there is no point. The thing is, I realized I have to go back to the basics. I have to go back to something that doesn't crash typescript, and that is easier to understand, that can be human readable, even though we are turning into AI stuff. So what is the most basic type we can have to associate a route to types? So we have type params and stuff. And if we specify the name as a key, and then we have some kind of object that define the different properties of the route, this is still human readable, okay? And it becomes very powerful, because we can use the key of the map, just to get all the names, and then we can get the params of every different route. Now the actual type is a little bit more complex, but it's still readable. And so the good thing is that we can apply this to any other helper type that exists in, I mean, helper type, any other type that exists in vue Router, and make them typed. So they no longer allow you to just pass a string on the name. It becomes a union of many different strings. And so this is where Unplugging vue Router comes. Now I know it's not a fancy name. It doesn't have a cute logo, like Pina, but this is just because I want to stay as close as the name of the library, vue Router itself, and also because it works with different things, vite, Rollup, webpack, et cetera, et cetera. You can use it without any option. Now this is not something new on itself when it comes to the file-based routing. It's something that has been existing for a long time, okay? Since 2018, I think, Katashin, another member of the vue.js core team, made this. And even today, one of the most common plugin is vite plugin pages by Han, I think. So I'm introducing other things, and this is specific to vue Router for some reasons. The idea here, and this is the cool part, is that you only need to change all the imports from vue Router into vue Router Auto. And this is going to give you the types that are typed based on your route. So the thing is, you're still in control. You create the router, but you no longer pass the routes, which is the big boilerplate part of the routing, okay? Oops, sorry, that was a bit fast. You can still modify the routes array. And this is the runtime changing. You can extend the routes. And you can also do it at build time. So you can, in your V configuration, add any routes, and they will actually be typed as well. So your code will recognize everything. So how does it work? How does it look like? So instead of just pushing an interpolation of a string here of a route, this is a Vitez example, by the way. What we do here is we can pass the name, which is going to auto-complete here. So we can select the route we want. And then we're going to be able to add the params object. And that params object is going to tell us, hey, you're missing an ID here, as soon as I put the curly braces. And so we have the auto-completion, and not the ID, the name, sorry. But basically, you get the idea, right? You can pass any param you want here, and it will be safely typed. So you don't need to switch to the browser to see about problem. You will see it right on your editor. So you don't have any context switch. There we go. And then I think I delete that line, because it's just not a good one. All right. Now, when you get the route with useRoute, you have all the possible routes here that can appear in your application. But when we are in a page, this is name.ui, see the file name up there? We know that there is a name param on the URL, OK? So how do we tell useRoute that this is the actual, we are sure this is the route that, this is the route high name? So we can pass a generic here. So I'm going to write high, that bracket name. And then the route becomes one specific version of the application. And of course, this generic, as you saw, it didn't auto-complete. Now I think they changed that in recent typescript, maybe five. But I also added the version that allows you to pass an argument, because that one does auto-complete. So you don't even need to think too much about it. Now the way it works, it's by generating a big type route DTS that you can configure. You have this route name map. And then you have some extra, so you have overrides of all the types of your router and functions. And then the idea is, so I was talking before of how we are making things that you do very often easy to do, OK? And all the things that are less common are harder. But the idea and the key is not to compromise that flexibility. You should still be able to do everything you were able to do before, which is the configuration. So here is the defined page macro, which, well, I know we're doing a lot of macros here, define, define, define something. So just another one to remember. But the idea is you can pass all the properties you were using on the route configuration, on the routes array. The difference is that we are on the page. So there is no context switch. We're staying on the same component where we define things. And we can add anything we want. We can also have JSON blocks or YAML or other things if you want. And so the cool thing is that because this is going to affect the actual types. If you change it here, so I'm going to define page and change the name of this route to something else. So I'm changing my own name here. I'm going to save, and I'm going to get an error here because this name does no longer exist. So you get instant feedback like that. And then I change it just to make it match. OK. So closing that chapter, there is other things that we can make to improve the APIs. One of them is data loading. Now data loading is a huge topic. But today we have different ways of handling. And this is, in my opinion, one of the reasons it's not such a great api at the moment. Or if there is an api. There is no one api. So we have different ways to do it. We have watch on the params. But we have no list state, no errors, no SR handling. We have all the navigation guards. But it becomes duplicated and it can be verbose. And it's definitely not typed. Except with the plugin, of course. Then we have global navigation guards, which can enable you to create a custom data solution. And I will say this is the most convenient solution. And then we have suspense await, which I have a whole slide for them anyway. But they all have issues. OK. They all present some issues that doesn't allow us to use them at data fetching solution. So suspense on the surface is just perfect. We just put await on the script. There is nothing as simple as that. And it certainly has a few pros. It's very straightforward to write. The most straightforward to write, to be honest. It has some error handling. And it handles SR out of the box. But it's still experimental, although it should be changing soon. And more importantly, it doesn't update on navigation. It's not connected to the navigation. It's connected to a component. But these are two different concepts in reality. Although it can be coupled if you want. And the data is limited to the current component. If you want to use something you fetch in a page, in other components, you either put into a store or you pass it down as a prop. Or inject provide. But they have some issues. So what I want to introduce to you is data loaders. So data loaders are just functions that return data. And then they give you back a composable. This composable, you can use it on the same component, but also in other places. And it gives you access to the data itself, but also loading state, errors, and stuff. And it handles ssr, et cetera, et cetera. Now the key here is to export the loader. You don't actually need to write the loader here. You can write it anywhere. But it has to be exported by the page so that the router knows this page is loading this function, this data. And then you can reuse it anyway. But this also means that we are completely duping requests. So if you are getting the user profile in many places, you are using the user data in many places, we still do one request. We have all parallelization by default, but you can actually be also, you can also make a loader depend on another loader if you want. And they are effortlessly typed. Because we're just returning the data, if we don't write any type, it's still going to be typed by default. Nothing, I mean, you can explicitly type if you want, but it just works out of the box. And of course, you can export multiple loaders. Now the whole topic is a bit longer, and I don't have any more time. I'm already over time. But I invite you to check the RFC, which still have some time. The idea goes a little bit beyond that. Some client cache, site cache, simple. Some support for vue apollo, vue Fire, SuperBase, et cetera. And it's still experimental. To summarize, what I said is that we make predictable routes by having a fail-based routing because we have a one-on-one mapping and we know how things are going. And this allows our type, our tool, sorry, to generate the types for us. We have, therefore, a less error-prone environment, sorry, because we have the errors, we have, we're more likely to not do errors without the completion. I know we have to compile nowadays, but it still makes mistakes and the compiler doesn't. And so we have less boilerplate because no routes are arrayed and no context switch because we're still on the page. Sorry, I really went very fast because I'm really over time. Here are some links you can check. The slides are on esm.es slash stop writing your routes, just the initials, should be very easy. And thanks for your attention. Excellent, Eduardo. That was extremely interesting. And I love the design of your slides. They're like super sexy. Okay. So, let's check out the questions. But before everyone's first, I have one. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question. I'm going to ask you to give me a question.