But Can Your GraphQL Client Do This? — A Deep-Dive Into urql

Hello, friends! Thank you so much for having me. So today I'm going to talk about Urql. In particular, I'm going to dig into some of core values and standout features.

So a quick intro just on me. My name is Kaddy. I'm currently an engineering manager at Mutable, where I'm spending most of my time building mobile apps, both in React Native and GraphQL. I've been partial to GraphQL even from before I started using React Native, but having used both REST and GraphQL in mobile applications, I can definitely see how many of the benefits of GraphQL can be particularly useful for mobile. And I really hope that one day, GraphQL will be the standard for native applications.

So why am I here talking about Urql? Well, Urql is a GraphQL client for React, React Native, and others, and it's an open source project built by Formidable, and that's a company I work for. So what is Urql? At Formidable, we invest a lot in open source. We're all standing on the shoulders of giants here, and I mean, this very conference wouldn't even exist if Facebook hadn't decided to open source GraphQL in the first place. At Formidable, we have various initiatives to encourage folks to contribute to open source both within formida sauce, but also to personal and community projects. Urql is one of the many open-source projects over the years, but currently I think it's the most exciting one. Originally, it was created by Ken, then rewritten by Phil and now with contributions from the community as well as many of my formidable colleagues. Even I myself have not not long ago contributed by adding an auth exchange for handling authentication and token exchange, but more on that later. With that in mind, should you use Urql? Well, there are several other GraphQL clients out there. Apollo Client and Relay in particular. Ultimately, the choice on what GraphQL client to use and or not to use should really depend on the features that you need on your project. For the rest of the talk, I'm going to go through some of the features of Urql that I think are especially cool and just talk a bit about the general philosophy and the thought process that has gone into designing them.

All right, one of the things that really stands out in Urql compared to others is the commitment to first-party support for framework bindings. So, outside of React, Urql has first-party built-in support for Next.js, Preact, Svelte, and Vue. Although there are no plans to add bindings to Angular, so if that's your jam, you might have to look elsewhere. Apollo Client and Relay don't provide any kind of first-party support for any framework bindings outside of React, and they rely fully on third-party libraries. This is completely fine. Those libraries were designed for React, after all, and it's the community that wanted to use them for other frameworks. However, this can have detrimental ripple effects. For example, when the library implements new features, or breaking changes and upgrades, all these take time to propagate into the third-party libraries. If you have first-party support, these changes are built into the bindings from day one. If you're interested in a more detailed comparison of these libraries, there is a whole section on the article docs where you can find a pretty honest feature comparison between Urql, Apollo Client, and Relay. However, for the remainder of this talk, I'm going to focus on Urql only.

If there's one thing we know when it comes to tech is that things change fast and all the time. New language features come, libraries, conventions, the things that are cool change, and even business requirements crop up all the time.

When creating Urql, one of the goals was to make sure that it's as flexible as possible, so it would be able to adapt to the changing tech landscape. So in order to make Urql as adaptable as possible, it's built to be as extensible as possible.

Extensibility really is at the heart of Urql, which brings us to exchanges. Urql is built on exchanges. So if you have a think about what a GraphQL client does at its core, it takes a request, a query, or a mutation, and it gives the appropriate response, so a cache hit, a response from the API, or an error. So as a result, most GraphQL clients, including Urql, are built to be stream-based. So an exchange is just a plugin that allows you to inspect and modify both the incoming and outgoing streams.

Let me show you this, by example, because that will make it a whole lot clearer. When you install Urql and execute a query, by default, Urql uses three exchanges. These come packaged into UrqlCore. So we have the dedupe, the cache, and the fetch exchanges. All of these are completely replaceable, by the way, so you can swap out any of these for custom or alternate implementation.

So first, the dedupe exchange, it removes duplicate requests when the exact request is already in flight. So imagine a website with a header and a sidebar. And both of these want to display the user's name. Both of these will use a use query with exactly the same query. What the fetch exchange, the dedupe exchange does, is it makes sure that only one instance of that query is passed on to the next exchange, and therefore, removing the need for a duplicate API request.

Then the cache exchange returns the data from the cache if there is some. And finally, the fetch exchange, which will always be in the last exchange in the array, does the actual network request and puts the result back into the output stream. Then the result is passed from the network request exchange to the cache exchange, where it is stored for next time, and finally, it's passed back to the use query result.

Now, since you can literally add an unlimited amount of plugins, the only way to guarantee that they're all playing nice with each other is to make sure each plugin remains unopinionated. Let's have a look at an actual example of this in Exchanges. First, we have the fetch exchange that we already talked about. This is the default fetch exchange included in Urql Core. It fetches the data from the API and adds to the output stream. Now, a separate package add-on, you can install a separate add-on package for automatic persisted queries in a persistent fetch exchange. So, this exchange used the same fetch logic as the actual fetch exchange. But with automatic persisted queries, basically the way it works is that it allows server-side caching of GraphQL data.

So, the server can cache the request based on a shard of the whole request from the client side. And then on the client we can ask the server a particular request just based on the shard. And if the server had already had a request exactly with that shard, it can return the response from the cache, the server-side cache. Otherwise, it will say, oh, I don't know anything about this. Please give me more info in which case we can actually do the query.

Now, the persisted fetch exchange should be placed before the actual fetch exchange because firstly, mutations aren't cached and therefore they can't be passed on. They need to be passed on to the fetch exchange to handle. Secondly, if the server doesn't support automated persisted queries, in which case the request, again, will have to be passed to the fetch exchange. A different example, if you wanted to enable file uploads, you could, via multipart form data and post requests, you can use the multipart fetch exchange. This exchange uses the same fetch logic as the fetch exchange, but it's a drop-in replacement for the default fetch exchange. It will add exactly like the fetch exchange, unless the variables it receives for a mutation contain any files. And lastly, as you might have guessed, you can also combine the two exchanges in a persisted multipart fetch exchange that will support both automated persisted queries and file uploads.

In general, Urql aims for a batteries included approach, meaning that it's like a one stop shop for everything you need from your GraphQL client. Thankfully, because of the fundamental architectural choice of relying on an opinionated exchanges, every new feature or enhancement can be plugged in play with the appropriate exchange. Now, we've already had a look at the fetch exchanges, but let's have a glimpse at a couple more. One handy exchange is the retry exchange, which allows you to automatically retry requests. You can configure a delay, which can be a fixed value of seconds or a random value, and the maximum number of retries. And one close to my heart is the auth exchange.

So, authentication in GraphQL has been my pet peeve since forever. I've had to implement it several times and it's always been painful. There's actually an additional difficulty with React Native compared to the web because the token storage is asynchronous, which needs to be accounted for when fetching the initial auth state. So, with the auth exchange, my goal was to make it extensible so that it could be used for both React Native and for web and for the different implementations of auth. So, it supports both React and React Native. That is, you can fetch the token asynchronously or synchronously. It supports token refresh, and both as a mutation and as a separate fetching point. You can set your auth header, whatever way auth works on your application. So, sometimes you have a bearer token or sometimes just a token or maybe some additional headers. And finally, you'll be able to determine what constitutes as an auth error in your API and log out or handle that as needed. So, some APIs use, still use HTTP error codes for auth errors and some APIs use auth codes and those can be configured in a variety of ways. So, the auth exchange support various implementations on a server side.

Regarding DevTools. Now, I won't go very deeply into DevTools, but suffice it to say, Go has DevTools and surprise, surprise, you can install them as an exchange. This is available as a Chrome or Firefox extension or as an Electron app. With the DevTools, you can inspect the queries, results, timelines and also execute requests directly from DevTools, which can be really handy because it will use all the exchanges that you have configured locally.

All right, time to talk about caching. By default, Urql uses document caching. It will avoid sending the same request to the GraphQL API repeatedly by caching the result for each query. This basically works the same way as a cache does in the browser. So, Urql creates a key for each request that is set based on the query and its variables. Once a result comes in, it's cached indefinitely by its key. This means that each unique request can have exactly one cached result. However, when we cache queries, we also need to invalidate the cached results we needed. So, with document caching, we assume that a result may be invalidated by a mutation that executes on data that has been queried previously, cache invalidation is done only via the type name property. So, when we send a mutation that contains types that another query's results contains as well, that query result is removed from the cache.

And this brings us to the alternate caching option for Urql, normalized caching. Document cache is straightforward and effective, but it has some limitations. So, before we go into normalized caching, let's have a look at why it was necessary and what were the limitations for document cache. Firstly, as your application grows, it starts duplicating a lot of data. Consider, for example, a paginated list with filter parameters. Because the cache is keyed by the query and the parameters, you'll end up storing the same items multiple times. With document cache, because we only use the type name for data and invalidation and not any kind of ID, there's no way to actually automatically reconcile the data. And this leads us to number three, which is that if your application has any mutations, you won't be able to have offline support with document cache. The normalized caching solution for urql is called graph cache and is designed to solve these hard problems. Remember the whole extensibility from earlier, exchanges being unopinionated and replaceable? Well, graph cache is a drop-in replacement for the default document cache. I'm not going to talk very deeply about graph cache but I'm going to mention the four main features, well some interesting features from when it comes to graph cache. Firstly, obviously we've got optimistic updates but the unique thing about how graph cache does optimistic updates is that it never actually touches the real data. It always creates a layer on top of your existing data. When the query succeeds it actually executes your custom updater on the real data. So while we have the source of truth from the server, your real data is unmodified. I know that other cache solutions tend to like create a mock record with a mock ID and then replace it later, so graph cache does none of that.

Secondly, we've got schema awareness. This means that we fetch the introspection query and so we can make the cache aware of it. Then you can be warned when you're doing something wrong, for example, if you're using the wrong type of condition as a query, invalid fragments, querying unqueryable fields, things like that. And then given that the cache is aware of your schema, it can also serve you partial data. So a good example of this is, for example, a e-commerce site. So on an e-commerce site, you have a list of products, and in order to display this list, you would usually query, just the image, name, maybe the price. Whereas if you go into the product detail page of that product, you will have all kinds of details around sizing, materials, et cetera. So with partial data, when you go from a product list to a product detail page of a product, we can actually return the data that we already have in the cache. So you can start, you can display the image name and the price straight away without waiting for the product return with all the details.

And finally, and this is actually really important, commutativity. This is the driving force for being able to do offline first, ensuring that queries are applied in a cache in the order that they are executed. So for example, if you do three queries in order, there's actually no guarantee that they come back from the server in that order. So if the second query gets returned first, what Graphcache does is that it actually applies it the same way as an optimistic update on top of your cache. Then finally when the first query comes back, they will get applied in order. So with Graphcache, we can build offline first apps, and that is amazing.

For me personally, I find it especially powerful for mobile applications where users expect a level of functionality even when they're not connected to the internet. With schema awareness, optimistic updates and commutativity, Graphcache is built to handle offline support effectively.

And finally, what about bundle size? Well often the first thing that comes up when talking about ERCO is how small it is compared to alternatives. And well, yes, the bundle size is small and there are numbers for it. But rather than actually focusing on the numbers, it might be important to focus on why effort was put into reducing the bundle size. Ultimately, the smaller the bundle size, the shorter the parsing times. Graphcache also has a low memory pressure impact and is fast on slower devices. We want to ensure that users in countries and areas around the world with slower internet connection will still get the best possible experience on the web. This leads to a fast and inclusive web.

That's all from me. I really hope that you found this insight into Urql valuable. If you want to know more, I'm going to leave you with two main resources. Firstly, obviously, we've got the official documentation. It's really thorough. You'll be able to find additional information and on all the topics I covered here today. But more importantly, we've got the Urql community, which lives in the discussion tab on GitHub. I would honestly say this is one of the huge selling points of Urql. The core maintainers make keeping eye on it a priority and all the discussions are responded to and you can ask pretty much about anything regarding Urql from implementation issues, off to a feature request, or even ask for elaboration on the e-source around the library itself.

Thank you very much. Hello. Hello, Caddy. Good to see you again. Oh, good to see you again. I like the makeup.

You've gone all out. Yeah. Today, we're going for the inverted color. Yesterday, it was like a black background and white stars. Today, it's like okay, I don't know. I'm not Korean. I have a whole different vibe. So, we went for the inverted color scheme. The eyeliner. Yeah, thank you. You've got to do something with this MC gig, right?

Yeah, so, Urkel, your talk. We even have a number of viewer questions. Are you ready to answer some? Okay, let's do it. All right. Question one from Alexander. With first party support for such diverse frameworks, how do you ensure that your support has the best possible integration? Are all the frameworks which integration is provided in use by Formidable? So, not all of them are in use by Formidable. For example, the Vue integration is quite recent and we don't have any Vue projects, as far as I know. I know that all of the framework bindings have got maintainer kind of approval. So, what we try to do is, I know that when the framework bindings are created, they are run through the maintainers of that framework so that they're like, yes, this sounds right, or like, no, you've missed something.

That's interesting. So, you knock on the door of the project maintainers and go like, I have something, please approve. Well, pretty much. I mean, people are genuinely quite happy to have things that use their framework that they themselves don't have to maintain. So, it's actually quite a popular offering. Yeah, the dream of open source, right, where people do come together and do work rather than the reality of open source where often it's just still you doing all the work. Yeah, yeah, exactly. All right, question number two from Djapar Dejad. Just out of curiosity, does Apollo client have a similar concept to Urkel's DDoop exchange? Now, that's a sneaky one, because it's going completely off talk spec and asking about your Apollo client, but let's see. Oh, I think that is, I'll be honest and say I don't know. I think so for any questions that you don't like that I don't know, I really suggest going to Urkel's GitHub repo, to the discussion tab and asking on there.

And Phil and Jovi, who are the core maintainers, will get back to you within, you know, a couple of hours at the tops. So that one, I don't know, I'm afraid. No worries. Hey, it's always good to say you don't know. When you don't know, otherwise people get really angry when you just make up answers. Strange. Yeah, with that. It's like, oh no, you can use it in production today, runs away.

Okay, question number three from Juan. When you say it removes duplicate entries, do you mean it would remove duplicate fields in the same query? For example, what would happen if query 1 is asking for name and age, and query 2 is asking for name and nationality of a person? Note both requests used the same query of type person. We can then return name, age, or nationality. That is another excellent question, Phil or Jovi. What I would assume is that it is keyed by the actual query, so the whole querying thing would have to be the same. But I'm not 100% sure. Fair enough.

So what I've done is I've scanned the questions that are coming up. I will say a strong theme is, what about Apollo? So to the audience members, as someone who has used both platforms, the Apollo docs for the Apollo questions are probably super key. But let's run through these and see what we can do. Question number four from Radha, very high level. How does Urql compare over Apollo? And I assume they mean the Apollo frontend client rather than their server offering? Yeah, so compare in terms of implementation or philosophy, I guess, is the question. The question doesn't specify, so you get to pick whichever one you want.

Yeah, so they are similar in that they are both GraphQL clients. You know, in the front-end space, the original intent was to use with React. They are actually quite different when it comes to kind of the ideas around it and quite different around cache management. So, Urql wasn't really built to be like Apollo, but better. It was kind of going back to the drawing board around creating a GraphQL client and like, what do we actually need? Like from first principles, so start from scratch. And over time, for example, the hooks API. So, you'll notice that the API for interacting with Apollo clients and Urql is quite similar. So, you still have the use query hook because that's cool these days. You know, you're still parsing in a GraphQL as like a string because, you know, that's how you query GraphQL clients.

So, there are similarities just because both libraries have arrived at a similar solution, but they are quite different from kind of the ideas behind them. So, one thing that's really awesome around Urql, and I think as far as I'm concerned, that's like the number one reason to look into Urql is that the community is extremely responsive. So, if you have a problem or a question, like an implementation problem or just a question like some of these that I've been unwilling to answer like all you need to do is go to discussion tabs on Urql and unless your comment is like a troll you're pretty much guaranteed to get answers. So, if you have a look at the discussions you'll, you know like none of them remain unanswered, which is really nice because basically you know that if you decide to go for Urql like based on the features that it has, then yeah, you'll know that you'll be supported. You wouldn't get a position where you're like, oh it doesn't do what I want. Is it even possible? There's someone to ask. Whereas, with Apollo clients just because there are so many other products that Apollo manage like the client is just one small, like for them, open source offering and you know, it doesn't always have, you know, the number one support priority. Yeah, I can definitely relate to that. I do a lot of work in Federation which is one of the smaller offshoot arms of their open source offerings and you know, they're definitely very helpful people but sometimes when you're like deep in some rushed query plan I like, I think this is probably very low on the massive stack of products to maintain so here I am trying to figure it out for myself. Yeah, exactly and also like the community. I know so, well I'm sure a lot of you know so Phil and Joey are the kind of two lead people like both in building a lot of Urql and all of Graphcache but also managing the community and their number one priority is to make the community kind of friendly and helpful and then that, you know, everyone just wants to help each other build awesome things.

Okay a question for me now. You mentioned that Urql is very, very small. How does it achieve this? Because obviously I mean every bundle, every library would love to be small. What makes, what are, what are you, what's the secret method you're applying to make sure that Urql remains tiny? Um I think that's something to ask Phil. Yeah it's dark magic. It's, it's like, so Phil has this little black book as you know people have black books of like phone numbers and stuff. He has black books of hints on how to make libraries smaller. I also have a small black book. I just noticed but it just says, can we, let's see if the camera focuses. Nope absolutely fail. That's okay, it says list of enemies on it. Maybe if we're right next to my face. There you go. It just wants to be near your face for some reason. Yeah exactly it's like the face detection is very important but instead has a note about off zero inside.

Okay let's get somewhere. Oh I was gonna say for a more serious answer to that question it's actually, so firstly it's making sure that each of the components of Urkle are like separate libraries. So there's Urkle core which is like the core of the library which kind of, you know, it does the Urkle thing, it kind of manages the stream. And the very vigilance in what gets in that library. So you wouldn't just have kind of trash that you wouldn't use. And then everything else is in Exchanges. Sorry? You don't have LeftPad in there. No, definitely no LeftPad. Yeah, so then everything else is kind of in Exchanges. So Urkle is built to be modular. So anything you want, you just kind of get an exchange for it. So like the core is the absolute minimum that you need, which is why it's so small. And then you kind of plug in place, you pull in just the bits that you need. And because everything's in its own little library and also minimizing dependencies, so you wouldn't install LeftPad, you wouldn't install LowDash, so it's like the smallest dependencies that are possible. Yeah, that's pretty much it.

Yeah, I'm going to pick another question from the list of questions, which is a biased pick and you'll quickly realize why. From Alexander, any plans for supporting Rescript as a usage language? I've not heard of this. Rescript? Rescript is what they rebranded ReasonML as. Oh. Oops. Uh, I— No, it's okay. It's okay. Sorry. My house is going through a tunnel. And we're back. Don't worry. Yeah, nothing to see here, folks. Um, oh, so the— Oh, apparently Reason is supported. And Rescript is coming soon. Neat. Well, there we go. Um, cool.

I'm going to combine two questions here. I hope you don't mind, Nikan and Bastiaan. Are there any big obvious feature— any big obvious features that Apollo has which Urkel doesn't, and if you were trying to do like a drop-in replacement, could you predict any breaking changes? Um, so you can't— so the API is very similar, but it's not identical. So you can't just, you know, replace UseQuery with UseQuery, like, from Urkel. Because I think if I remember correctly, so I know that Urkel returns an array from UseQuery, whereas Apollo returns an object. So you have to change the destructuring. So like there's a small way to do it, so like there's a small API change, yeah, between them. Outside of that, let me think. So if you're not using cache, so if you're just using, like, just doing some queries, doing some mutations, we don't have a custom cache implementation or anything like that, I think it would just work. If you have a custom cache, then obviously cache implementation is slightly different. The way that you interact with is slightly different. It's an exchange that you drop in, and then if you have a cache, and if you do, for example, offline or optimistic updates, you need to also write the update queries for those. So those could be slightly different. So basically, if you have a simple implementation, which is just some queries and mutations, I think it would pretty much just work outside of just changing the syntax slightly.

Neat. And another question for me, how did you pick which libraries you support? We had things like Preact, for example, which is a less commonly used component-based web framework. How did that list get put together? Is it just stuff that Formidable has wanted to use at the time? Or is there more planning involved?

Well, I think, so Preact support is, well, Preact is a drop-in replacement to React, which means that Preact support is actually very easy to achieve. So why not have it? Also... And it's like, oh yeah, we also support Preact, because everyone does technically. Yeah, exactly. But also, Jovi is a Preact core maintainer. So there's also in-house expertise to answer the other question, how do we make sure that our framework findings are up to par? If there's ever an expert on Preact framework findings, it would be Jovi. So that was a pretty easy one.

The other point of view, I think in general, there's just a framework that we're interested in, like outside of Preact. And that's what those robots are all about. Angular, I think there isn't a huge amount of like not a lot of Orcle maintainers, but there hasn't been a lot of interest in Angular. Yeah, the Venn diagram where people who want to use Oracle and the kind of people who use Angular are probably not super in, the intersect of that's probably quite thin.

Oh, actually I had an answer to a previous question that I forgot to mention, which was around, I think I didn't answer the second part of the question, which was around what does Orcle have that Apollo doesn't. And like one of the main things was around Graphcache. So Graphcache is built to be from ground up to be able to work offline, which is very exciting because basically like with Apollo, they're kind of, their cache is kind of state management. Whereas with Orcle, the Orcle cache is kind of a mirror of the server cache. So it's meant to be your local server cache and all the updates are applied in the correct order. And yeah, so basically the way that it's built from the ground up is to be able to support offline, which I'm pretty excited about for React Native because I think it would definitely be a game changer, which means that if you have an app with optimistic updates and using Graphcache, you can pretty much make it work offline, which is awesome. Yeah, no, that does look really cool. It seems like a very clever way of dealing with a common problem. I've seen so many hand rolled implementations of what always ends up being more or less persistent queries. Yeah, yeah. I mean, I've created some implementations using Apollo trying to achieve offline first, and I think with Graphcache, it's actually the first time I feel like it works and I'm kind of confident in the solution. Yeah, and I have some plans to create some tutorials around that, so I think it's a very exciting thing for React Native. Mm-hmm.

Okay, wonderful. Well, I think we've answered all the questions we have, and I think my camera is also becoming more haunted over time, so maybe we should wrap up for now and have a fiddle with that. Is there anything else you would like to say, promote? This is your chance to plug to the audience. I would love to have more people give urql a try and just give us feedback.

Like, I know I keep saying the community section in the GitHub site, but that is the go-to place. Like, you try urql and go like, oh, I don't like it because it doesn't do this thing. Just post there and then we can answer. We can maybe say, oh, yeah, it's planned. Or, we're not doing it because of this. So, just really keen on people to try it out and give some feedback.

Well, there you go. There you have it. Give urql a chance today. Thank you very much, Cady.