The new GraphiQL: Next-level Customizability

Hello folks. Welcome to my talk at GraphQL Galaxy. I hope you're having an awesome conference so far, enjoying a lot of other interesting talks, and I hope I've got another interesting one lined up for you now. And I want to open it up with a question to you. Why do you think GraphQL is so successful?

Now, I'm recording this talk, so I can't get your answer straight away, but feel free to drop your answers, comments, questions, whatever, in the chat, and let's see that we can get a conversation going. And I'll give you my answer. I believe GraphQL is so successful because of its tooling. And one tool in particular that you can also see on the screen already that I want to talk about is GraphQL.

GraphQL has been around since the release of GraphQL back in 2015. And to this day, it is the portal for me as a GraphQL developer to interact and dive into GraphQL. There's been a lot of development around GraphQL in the last year, and this is what I want to talk about to you today. And in particular, I want to focus on customizability and how you can take GraphQL to the next level.

Quick facts about me. My name is Thomas, I work at Stellate on other cool GraphQL things, and I'm one of the maintainers of GraphQL. But enough about me. Let's dive right into the topic. And I want to start with the why. Why does GraphQL exist? Let's rephrase this to what are actually the problems that GraphQL developers face? Before we talk about any kind of solutions like GraphQL.

If I'm just getting out, a big thing that I need to do is just learning. I need to learn actually what is GraphQL? How does its syntax work? Was it a Graph QL schema, exploring a schema firsthand, and having this first success moment of sending a Graph QL request and getting a response and seeing both of them side by side? Once I learn GraphQL, I grasp the concept, then I want to get my hands dirty. I start developing and building my first Graph QL API. This involves a lot of iteration, and testing out queries as I go and debugging if something is not working as I expect it to.

Graph QL already contains the word Graph in its name and a Graph is something that can very easily be laid out in a visual way where I can explore, in this case, it's the Graph QL schema, and how different types relate to each other. But it's not just the schema, also the data that the API returns to me. It's depending on the semantics of the API, this data could have certain meaning like I don't know, geolocation data, which I can visualize in a very specific way. It's also a lot about documentation. If I'm in particular, if I'm building my own API, and I want others to use it, I need to document it. And I want this immersive documentation behavior where people can dive into the docs, read through the meanings and the workings of my API. And write in there being able to start writing queries and trying it out, having these interactive embedded sandboxes where you can just get going without ever leaving the documentation. And I also want to collaborate.

Rarely I'm working by myself on a project, so I want to share any kind of queries that I'm writing with my peers, maybe also debugging, and want to easily import export all of the operations that I'm writing between different tools that I'm using.

So all in all, a big set of problems. So let's see where does GraphQL fit in as a solution to these problems. Let's start with the initial, the version 1 of GraphQL, which was released back in 2015. This version was really focused and specialized on the learning, exploring and developing part, and it excelled at it. In fact, it's in my opinion a key reason why GraphQL took off and why it got so successful in the first place. Because we had this tool, GraphQL, at our fingertips, where you could just start exploring and playing with GraphQL without needing to set up or install anything. Just open it up in a browser window and go.

The other points, some of them might maybe take a few strides to it, but there was clearly room for improvements still left to do. And, in fact, earlier this year we released the next major version, version 2 of GraphQL, and we also looked at these problems and we figured we need to make GraphQL solve a wider range of these problems and make it more flexible. So what did we do? For example, we added a plugin API, so everybody can now easily write their own GraphQL plugins, which enables you to interact with GraphQL, with its UI, and also render additional components right into the UI that fit your specific API and your specific use cases. We also refactored GraphQL and broke it up into its individual parts and made all of these building blocks available with a new package called GraphQL React. And using these building blocks, it is now more easy than ever before to just take some of these components, plug them together and create your own custom IDE that is very easily embeddable into your products or your websites. Of course, version two is not the end of the road for GraphQL. There will be more things coming in the future and we want to solve an even wider range of use cases and make it even better, but more on that later on. Really coming back to what I'm trying to say here is that GraphQL has seen immense growth over the past years. And with each year there are new tools and new products entering the landscape. And I believe that GraphQL as a tool must not be fixated on the one thing that it did very well back a couple of years ago. GraphQL also needs to evolve together with GraphQL and its ecosystem.

So now is the exciting part because now I want to actually show you what this all means and how you can customize GraphQL. And for this I prepared a demo. I did setup a very simple React application, which at the moment just renders GraphQL. See the app component as my entry point here and it just renders the GraphQL component. And if I take a look at it in my browser, I will see GraphQL version 2, the new version also featuring a new design, but essentially it's the thing you know and love. If we enter a query on the left side, we can also format it and run it and we get back our data on the right side. Awesome. So let's customize this. First thing, maybe, or I hope at least to you, this looks visually appealing, but usually I want to make this blend in with my own product. I don't want to use the colors I see here. I want to use my own brand colors.

In version one, this would have been quite the hassle to do because all of the styles were scattered across different style sheets and we used the same color in multiple places. But with version two, we extracted all of this into CSS variables. So the only thing I need to do now is basically override a set of color variables which I'm doing here. If I save this and go back, then here we have it, GraphQL in a completely new coat of paint. As easy as that.

But the looks is only part of customization. Maybe the, or probably the way bigger part is functionality. And I wanna take you through an example of how we can build our own custom functionality right into GraphQL. And the example I'm thinking of is timing data. If I run a request, I see it's loading for some time, and then I see the data and I wanna see how long does this actually take. I could now open up my dev tools and my network tab and send a request and then I'm seeing, okay, this took 285 milliseconds, but this is tedious. I have to jump around between dev tools and actually GraphQL. I want to build this right into my UI. Let's do this.

The thing to start is the so-called Fetcher function. The Fetcher function is a function that fetches a GraphQL request, obviously, and currently we're using this utility called createGraphQLFetcher, which allows us to just pass in an endpoint and it spits out this function. Super easy. But for our purposes, actually, we want to customize this now, because we want to actually measure how long does the fetch request take. And I already prepared a little rewrite, where we are taking basically what this createGraphQLFetcher function does and just expand it, basically. So manually writing out this function, and it looks something like this. We are getting two arguments, the GraphQL params, which is essentially just a body that we're sending with the request, and an options object, which in particular contain the headers that you can add in the GraphQL UI down here. And what we're just doing simply is, we're sending a fetch request and then we're returning the data as JSON. I'm gonna save that quickly and we can see that actually everything still works as expected. So with that, we can start getting some timing information, and I'm just gonna use some timestamps using dateNow. And to prove to you that this is working, I'm gonna log out this on the console. So if I open up my console now, I see each time I make a request I get the timing information on the right. Awesome. But again, I don't wanna have this in my dev tools, I wanna have this in the UI. So how do we get this in there? We're gonna use plugins. Plugins are the things that you are seeing on the left side here.

There are two built-in plugins, the docs and the history, but you can easily create your own plugin. So let's just do this and also again prepare this. A plugin is essentially just an object. We can use the graphical plugin type from the graphical React package I mentioned before to make sure we implement it correctly. It just has three properties, a title, which is just a string. An icon, that's a React component, which will render the icon here on the side. I'm just going to use a very generic icon for this. And content, which is another React component, which will render the content here on the plugin pane.

So all we need to do is take this plugin and pass it as prop to GraphQL, save this, go back and we see here we have a new icon and we have a new plugin. And it's as easy as that. So all we need now, basically, is we want to show the timing information here. So we want to have some kind of timing variable that we want to show here. And we are actually going to use just a plain old simple React context for that to consume this data. And this is now speed running through creating this. So adding the context, then also rendering the provider, of course, so that I can consume the context. I also need to pass its value. And we are going to store this value in state and import this. And now all that we have to do instead of logging this, actually, what we want to do is set timing here. But in order for us to be able to do that, we have to move the Fetcher function inside the component. One thing I'm going to add here is a use callback so that we preserve the function identity between renders. And we're going to save that. Heading back, and now if I'm sending a query and actually opening up my plugin, I can see I get my timing information right inside of my UI each time I send a request. Super nice.

And there's one more thing I want to show you now. I talked about embedding GraphQL into a page previously. And I also prepared a demo for this. Let's say, imagine you have your blog here, where you're blogging about awesome GraphQL stuff, and now I want to enable my readers to right inside of my blog, try out the concepts that I'm blogging about. So what I want to have is an embedded awesome GraphQL IDE right inside my blog.

So, let's do it. And this is the setup. So just some random lorem ipsum text. And I'm going to remove this gray box. And what I'm going to render also, prepare this again, so you don't need to see me excessively typing, I'm going to render the GraphQL provider. This is coming, again from the graphical react package. And this will set up all the state management that is necessary for GraphQL to function properly. We're going to pass it a fetcher again, which is the same thing that we have seen before. And we're also passing it a query, which is just a query that we think makes sense for the user to start out with in the example.

And then we're rendering our awesome GraphQL component. And it's again, a super simple component, ignore the diffs that you see here are just for layout and styling purposes. So that's nothing too important. The important parts are, we are using a component called query editor and a component called response editor. Both of which are also provided to us by graphical react. And the only other thing that we need to, or that we want to have, is, we also want to show a loading indicator when the query is while the query is loading. And for that, we can easily consume one of the contexts that graphical uses to manage its state. And in this case, we want to use the execution context, and we can just use the equally named hook from graphical react to access this context when you enter context as a property called is fetching. And if this is true, we're going to run a spinner. So let's save this and head back. And here we are. Here we got our little embedded graphical. I can press command and enter and my query is loading. You saw the loading spinner. And of course, it's not static, so I can still type and edit my query like a booting graphical, just smaller and embedded. Awesome.

This is actually, this concludes the demo. This is all I wanted to show, so let's head back to the slides. And I'm grateful that this worked out as it did and I hope you enjoyed it as well and learned something new.

So I mentioned something about version two is not the end of the road previously. So I also want to tell you, what do I mean by that? What are we looking at for future versions of GraphQL? The first thing on this list is Monaco, which is the code editor that also powers VS Code. Currently GraphQL uses a different code editor, but we want to introduce Monaco for various reasons. It has a more familiar editing experience since VS Code is one of the most used IDEs for coding. It's more accessible and it hopefully will give us a little performance boost.

Coming back to customizability, Monaco also has some very nice features for us to customize the editor experience. To show you an example, this is something that we've built at Stellate, which is a query complexity estimator. You see here on the left, right while I type my query, we inserted these little grey boxes exactly what complexity is added by a certain field, which is super useful if you're getting into something like graphical rate limiting.

The next thing on my list here is the Graphical Explorer. You might know the OneGraph Explorer, which has also been around for Graphical v1. We ported this to match the design of v2, but we want to go even beyond that. We want to really build this intuitive query build experience into graphical. And I want to give a shout out to Jonathan, one of the maintainers of graphical, who is excessively exploring and de-risking this effort, and built even his own prototype around to test out and validate the ideas that we have, as you see on the left here with the familiar visual query builder.

And the last thing I want to mention is again, plugins, because we love plugins, we believe plugins is the way forward to enable even more customization. And when looking at the structure of the graphical UI, you already have witnessed the plugin pane on the left side, which we used in the demo. But there are actually even more places where plugins make sense. For example, beneath the query editor or beneath the response editor and thinking back to our demo and the plugin that we built for timing, this would have been maybe more sensible to put beneath the response to better co-locate the timing with the actual response.

All right, so how can you take action? What can you do now after hearing and listening to this talk? You can install GraphQL version 2. It's out for a couple of months. It's got all the new features that you've seen here today, including the new refreshed design. You can also build your own IDE like we did in the demo using the GraphQL react package. If you want a reference of how to use this package, you can just look at the GraphQL in fact, which is using GraphQL react under the hood. If you have any questions, you can find us on Discord on the official GraphQL Discord. We have a GraphQL channel in there and if you notice something which is not working or have some ideas for improvement, then feel free to open an issue on our GitHub repository.

And with that, all I've left to say is thank you very much for chiming into my talk. I hope you enjoyed it, took a thing or two away. If you want to find me, you can find me on Twitter, you can find me on GitHub or also at Sted8 where I'm working on GraphQL stuff.