The new GraphiQL: Next-level Customizability

Rate this content

We shipped the next major version of GraphiQL earlier this year! We completely rethought the experience with a particular focus on customizability. Not all users and every API have the same needs for a GraphQL IDE, so one of our big goals was to allow GraphiQL to work for a large variety of use-cases. Let's dive deep into the changes of how we took the customizability to the next level and explore together how you can make GraphiQL your own.

21 min
08 Dec, 2022

Video Summary and Transcription

GraphQL is successful due to its tooling and customizability, but developers face challenges such as learning, syntax, schema exploration, API building, visualization, documentation, and collaboration. GraphQL version 2 has made significant improvements, including a plugin API and building blocks in GraphQL React. Customization in GraphQL involves overriding CSS variables and building custom functionality using plugins. The ability to embed a GraphQL IDE into a blog allows users to interact with GraphQL concepts directly. Overall, GraphQL continues to evolve and adapt to the changing needs of its ecosystem.

Available in Español

1. Introduction to GraphQL and Its Challenges

Short description:

Welcome to my talk at GraphQL Galaxy. GraphQL is successful because of its tooling. I want to talk about GraphQL, its customizability, and taking it to the next level. The problems GraphQL developers face include learning, syntax, schema exploration, building APIs, visualization, documentation, and collaboration.

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.

2. Customizing GraphQL and Its Evolution

Short description:

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. GraphQL version 2 has made significant improvements to address a wider range of problems and provide more flexibility. The addition of a plugin API and the availability of building blocks in GraphQL React make it easier to create custom IDEs. GraphQL continues to evolve and adapt to the changing needs of its growing ecosystem. Now, let's dive into a demo to see how you can customize GraphQL and make it blend seamlessly with your own product.

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.

3. Customizing GraphQL with Plugins

Short description:

In version two of GraphQL, we can easily customize the styles by overriding CSS variables. However, customization goes beyond just the appearance. We can also build custom functionality, such as measuring the time it takes for a request to load. By customizing the Fetcher function, we can add timing information directly into the UI. This can be achieved using plugins.

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.

4. Creating Custom Plugins for GraphQL

Short description:

We can easily create our own plugin in GraphQL by implementing the graphical plugin type. It has three properties: title, icon, and content. By passing the plugin as a prop to GraphQL, we can add a new icon and plugin. To show timing information, we use a React context and store the value in state. By moving the Fetcher function inside the component and using the use callback hook, we can set the timing and see it in the UI when sending a request.

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.

5. Embedding GraphQL IDE in a Blog

Short description:

I want to show you how to embed a GraphQL IDE into a blog. We can use the GraphQL provider from the graphical react package to set up state management. The awesome GraphQL component includes query editor and response editor. We can also show a loading indicator using the execution context from graphical react. The embedded GraphQL IDE allows users to interact with GraphQL concepts directly within the blog.

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.

6. Conclusion and Next Steps

Short description:

This concludes the demo. GraphQL version 2 has new features and a refreshed design. You can install it and build your own IDE using the GraphQL react package. If you have any questions or ideas for improvement, you can find us on Discord or open an issue on our GitHub repository.

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.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

GraphQL Galaxy 2021GraphQL Galaxy 2021
32 min
From GraphQL Zero to GraphQL Hero with RedwoodJS
Top Content
We all love GraphQL, but it can be daunting to get a server up and running and keep your code organized, maintainable, and testable over the long term. No more! Come watch as I go from an empty directory to a fully fledged GraphQL API in minutes flat. Plus, see how easy it is to use and create directives to clean up your code even more. You're gonna love GraphQL even more once you make things Redwood Easy!
Vue.js London Live 2021Vue.js London Live 2021
24 min
Local State and Server Cache: Finding a Balance
Top Content
How many times did you implement the same flow in your application: check, if data is already fetched from the server, if yes - render the data, if not - fetch this data and then render it? I think I've done it more than ten times myself and I've seen the question about this flow more than fifty times. Unfortunately, our go-to state management library, Vuex, doesn't provide any solution for this.For GraphQL-based application, there was an alternative to use Apollo client that provided tools for working with the cache. But what if you use REST? Luckily, now we have a Vue alternative to a react-query library that provides a nice solution for working with server cache. In this talk, I will explain the distinction between local application state and local server cache and do some live coding to show how to work with the latter.
GraphQL Galaxy 2022GraphQL Galaxy 2022
16 min
Step aside resolvers: a new approach to GraphQL execution
Though GraphQL is declarative, resolvers operate field-by-field, layer-by-layer, often resulting in unnecessary work for your business logic even when using techniques such as DataLoader. In this talk, Benjie will introduce his vision for a new general-purpose GraphQL execution strategy whose holistic approach could lead to significant efficiency and scalability gains for all GraphQL APIs.

Workshops on related topic

GraphQL Galaxy 2021GraphQL Galaxy 2021
140 min
Build with SvelteKit and GraphQL
Top Content
Featured WorkshopFree
Have you ever thought about building something that doesn't require a lot of boilerplate with a tiny bundle size? In this workshop, Scott Spence will go from hello world to covering routing and using endpoints in SvelteKit. You'll set up a backend GraphQL API then use GraphQL queries with SvelteKit to display the GraphQL API data. You'll build a fast secure project that uses SvelteKit's features, then deploy it as a fully static site. This course is for the Svelte curious who haven't had extensive experience with SvelteKit and want a deeper understanding of how to use it in practical applications.

Table of contents:
- Kick-off and Svelte introduction
- Initialise frontend project
- Tour of the SvelteKit skeleton project
- Configure backend project
- Query Data with GraphQL
- Fetching data to the frontend with GraphQL
- Styling
- Svelte directives
- Routing in SvelteKit
- Endpoints in SvelteKit
- Deploying to Netlify
- Navigation
- Mutations in GraphCMS
- Sending GraphQL Mutations via SvelteKit
- Q&A
React Advanced Conference 2022React Advanced Conference 2022
95 min
End-To-End Type Safety with React, GraphQL & Prisma
Featured WorkshopFree
In this workshop, you will get a first-hand look at what end-to-end type safety is and why it is important. To accomplish this, you’ll be building a GraphQL API using modern, relevant tools which will be consumed by a React client.
Prerequisites: - Node.js installed on your machine (12.2.X / 14.X)- It is recommended (but not required) to use VS Code for the practical tasks- An IDE installed (VSCode recommended)- (Good to have)*A basic understanding of Node.js, React, and TypeScript
GraphQL Galaxy 2022GraphQL Galaxy 2022
112 min
GraphQL for React Developers
Featured Workshop
There are many advantages to using GraphQL as a datasource for frontend development, compared to REST APIs. We developers in example need to write a lot of imperative code to retrieve data to display in our applications and handle state. With GraphQL you cannot only decrease the amount of code needed around data fetching and state-management you'll also get increased flexibility, better performance and most of all an improved developer experience. In this workshop you'll learn how GraphQL can improve your work as a frontend developer and how to handle GraphQL in your frontend React application.
React Summit 2022React Summit 2022
173 min
Build a Headless WordPress App with Next.js and WPGraphQL
Top Content
In this workshop, you’ll learn how to build a Next.js app that uses Apollo Client to fetch data from a headless WordPress backend and use it to render the pages of your app. You’ll learn when you should consider a headless WordPress architecture, how to turn a WordPress backend into a GraphQL server, how to compose queries using the GraphiQL IDE, how to colocate GraphQL fragments with your components, and more.
GraphQL Galaxy 2020GraphQL Galaxy 2020
106 min
Relational Database Modeling for GraphQL
Top Content
In this workshop we'll dig deeper into data modeling. We'll start with a discussion about various database types and how they map to GraphQL. Once that groundwork is laid out, the focus will shift to specific types of databases and how to build data models that work best for GraphQL within various scenarios.
Table of contentsPart 1 - Hour 1      a. Relational Database Data Modeling      b. Comparing Relational and NoSQL Databases      c. GraphQL with the Database in mindPart 2 - Hour 2      a. Designing Relational Data Models      b. Relationship, Building MultijoinsTables      c. GraphQL & Relational Data Modeling Query Complexities
Prerequisites      a. Data modeling tool. The trainer will be using dbdiagram      b. Postgres, albeit no need to install this locally, as I'll be using a Postgres Dicker image, from Docker Hub for all examples      c. Hasura
GraphQL Galaxy 2021GraphQL Galaxy 2021
48 min
Building GraphQL APIs on top of Ethereum with The Graph
The Graph is an indexing protocol for querying networks like Ethereum, IPFS, and other blockchains. Anyone can build and publish open APIs, called subgraphs, making data easily accessible.

In this workshop you’ll learn how to build a subgraph that indexes NFT blockchain data from the Foundation smart contract. We’ll deploy the API, and learn how to perform queries to retrieve data using various types of data access patterns, implementing filters and sorting.

By the end of the workshop, you should understand how to build and deploy performant APIs to The Graph to index data from any smart contract deployed to Ethereum.