GraphQL Code Generator v3: generate GraphQL types has never been easier!

Hi, everyone, and thank you for being here. I'm happy to be here to talk about the future of GraphQL Code Generator and to new features that we added recently that brings a brand new developer experience. So let's get started. My name is Charlie. I've been working full time on Code Gen for the last six months and especially working on the feature I'm going to showcase today and on the upcoming roadmap for Code Gen.

So, before looking at this new developer experience that Code Gen is bringing, let's take a look at the history of Code Gen and how we went from generating simple type to hooks to the new feature that we're going to see today. So, Code Gen has been created in 2016 to first generate schema types, plain TypeScript types, and then a bit later, in the same year, generating operation types — so, for the backend and also for frontend. But the first version of Code Gen, before 1.0, was just generating plain TypeScript types. Then, a bit later on, Code Gen started to bring support for generating types to many types of languages beyond TypeScript and JavaScript, such as Java, C Sharp, but also Kotlin, etcetera. And a bit later on, again, due to high demand on the front end, Code Gen started to generate like framework-specific plugins, such as Apollo Client, Yorkle, Vue, Angular, and so on. Code Gen, nowadays, is quite famous and present in most GraphQL stack, especially on the client side, with 7 million downloads per month on NPM.

And if we look at popular usage, Code Gen is very famous on the front end side, especially for TypeScript stack, but also on the back end, with TypeScript stack, but any kind of GraphQL server implementation. And if we look closer on the front end, because this is the subject of today, we're gonna talk about a new experience on the front end, we see that, nowadays, people are very, very happy with generated hooks in SDK.

So while generated hooks and SDK are very famous, we took a step back and looked at also the drawbacks that comes with this certain approach. First, the limitation of hooks and SDK that are generated by Code Gen are, first, replicating signature changes. So since Code Gen now is responsible of wrapping a lot of libraries on the frontend, like React, Query, Apollo, your call in React, but your call in Vue, Apple Angular, etc. All those libraries are living their own life and changing quite often and offering different spectrum of different options.

So we have to make sure that every time we wrap a library, we are providing access to the underlying specific options of each library and we are staying aligned with the different major versions. So this leads to a lot of pull requests, issues of implementation that are sometimes community-driven, that are not following the evolution of the wrapped libraries. The second one is the exponential number of options. So Kodrain itself has a lot of options to make it more tailored, more configurable and to make sure it fits well your usage of TypeScript in your GraphQL stack. But since we are wrapping existing libraries and it has to be flexible, also each plugin gets its own set of options on top of the dozens of options that core packages of Kodrain are offering. So this makes it very hard in the long run to make sure that every introduced new option is compatible with existing one, and that upgrading or changing the behavior of existing options is not going to bring anything in any type of plugin that started to diverge from each other. And finally, the last point is bundle size impact. So we are in a new era of front end and web application where bundle performance and you know bandwidth impact is very important. And Kodrain, when generating like wrappers such as SDK, but especially generating hooks, is generating all this code just to make sure that we forward the types properly and we type check the variable properly.

So all those of the version led to a very specific experiment that has been called Type Document Node. So Type Document Node, it's an experiment that started in 2020, and it started with a simple question. What if we could type GraphQL operations without hooks? What if we could bring the same awesome developer experience that everybody likes around using hooks that are similar to React but without actually generating hooks but using only types?

So this is a query on the left that returns a rate, for example for product, on a given currency. On the right, this is the code that is generated by CodeGen when using the TypeDocumentNode plugin. So as you can see, it's very similar to the early days of CodeGen. Very similar to what the TypeScript and TypeScript operations plugins are generating. The only difference is that here we use a TypeDocumentNode and TypeDocumentNode is a superset of the DocumentNode object and type from the GraphQL.js library and TypeDocumentNode, unlike DocumentNode, is typed properly by carrying the type of the query and the type of the variables. And this allows to have a perfect integration with your client. Here, in this example, you can see that we just import our document, so like you do in any application, you import your document and you pass it directly to the use query of Apollo. And immediately, you get type checking on the variable and you get type result. So here is the data is typed properly with the right query type from TypeScript operations and same with sub properties. So this has been made possible because Dotan and other people from the community has been working very hard to make sure that TypeDocumentNode, this new type version of DocumentNode from GraphQL, JS is supported by all the GraphQL clients in the TypeScript ecosystem. So over the years, all the following work led to a perfect integration in the GraphQL front end TypeScript ecosystem. You can already use TypeDocumentNode with Apollo Client, ReoCall, Preact, React Query, even is the VR. And you can use it also in Svelte, Vue, et cetera.

So here we can see that the vision it brought is that first Cogen has been created to, you know, generate TypeScript types and then it added some support to other languages which is still true today. But then it started to have a very specific approach inspired from React hooks to generate better and, you know, bring a better developer experience by generating more than types and generating code. And now we are closing the loop with a new developer experience that I'm going to show you right now. And this is not Type Document Node. Type Document Node is a stable way of using it, but now we are bringing an improved version of Type Document Node that has been developed first as an experiment by Lauren from the Guild and now it's been released as a stable plugin from CodeGen. And this new feature is called the Client Preset.

So this is a GraphQL query implementation with Apollo Client that uses the new Client Preset, the new developer experience of CodeGen. So you can see here that we don't import any type, we don't import any documents, the only thing that we import is the GraphQL function that has been generated for you by CodeGen in the same way that you import GQL when you are using Urql or Apollo Client. And the thing here is that this GraphQL function that we provide you is going to return the proper type document node type to your variable, depending on the query that you are passing to it. Which means that as just showcased with that document node here, by just using this GraphQL function to define your operation, this document variable is going to be typed, it's going to carry the type of the query and the variable, and is perfectly integrated with Apollo Client and all the other clients as they're showcased. So your data is going to be typed and your variable are going to be type checked. The good thing with this approach is that you don't need to import documents or types anymore. When using GraphQL in watch mode, your GraphQL operations get typed as you type, and finally the bundle impact is very light because here we are only generating one function that's being used the same everywhere and we are not generating like one hook per query and we are only generating types. So, all the types are removed at runtime and the only thing that remains is actually the GraphQL query. If you really want to have like a zero bundled impact with this new client preset, you can use the Babel plugin that we provide and that is documented that will remove the GraphQL function at runtime meaning that you will have a full end-to-end typed operation experience without any runtime impact.

So, let's now talk about another thing that is being bring by the client preset which is fragment masking. So, at the Guild and when it comes to all the projects that we maintain, we try to bring the best practices to the ecosystem and not only the thing that we think is the best for us. We are trying to show you what is the best thing to do with GraphQL when it comes to error handling but also typing things. And here, fragment masking is not that famous practice in the GraphQL ecosystem and we think it should benefit from more light and more recognition of the ecosystem.

So this new feature of Codegen is trying to bring you a way of using fragment masking in a way, in a very easy way. So let's talk about fragment in GraphQL. Most of us are using fragments to break down queries into data models. To basically take type and create sub-types of existing type so you can actually pad them in your component, etc, etc. The thing is that by doing so, here we don't really know, we have a UI on the right which is displaying a document and the title is part of the main component, but the acini is one component and the tags are also a dedicated component, and here by looking at the query it's not very clear which part of the data is going to be used by which component. Which makes it pretty hard to know which data is used by a component by just looking at one component without looking at the whole component tree or at least to look at the top component that is loading the data.

So this is exactly what fragment masking is bringing. Fragment masking is a concept that has been brought by Relay Team, so the initial creator of GraphQL which says that fragments should not be used to break down queries into data models. We should use fragments to represent the different views of our application and by views we say components. So each fragment should represent which data is used by a component. So let's put that into practice. Here we have the same query but we changed it. Since we have one component for document we're going to make a top fragment for our main component and this main component only needs the title and the id for the different actions. So here the main fragment for the dog view is going to have the title then the assignee then this component is instantiating two components one for the assignee and one for the tags so we're going to have two fragments that's going to really express what are the data dependency of our child component. Yeah so we have the dog view which instantiates the assignee we display the title instantiate the assignee and the tags and each sub-component gets its own fragment that is collocated with the component itself. So let's see a concrete example because it's very theoretical. So here we are having our client presets with a brand new TypeScript config of CodeJam so we have a schema which is local because this is an example we get all the TypeScript documents and we use a new preset client. Here we are having our app which is of course a dummy app with just to showcase the concept of fragment masking. Here we are having our document query, our document view fragment because we are into the document components. And here since this is the main component it's going to be the one that's going to make the query. So we make the query and like I told you here with the client presets the new experience we get tag checking immediately. So here it's complaining that number is not assigning it's enable to string. And here as you can see we are not importing any kind of document or type. We are just importing the GraphQL function everywhere. Then we say okay we are in the doc view so we use a special function that is exposed generated by GraphQL code gen to extract the data that is specific to this fragment. Which is the fragment of our top component.

Which is a document view fragment. And here in doc view we get all the data that this component should get access. So this component cannot access the data of children component. It only access the data of it's own fragment which is id and title. If we go down we see that we pass the doc view to the children component. And here for example let's take a look at the tags. So here we have co-location. Here it becomes very very clear that this component gets this data. It gets a subset of data on the doc type from the schema. It gets category created at status. In here you can see that I only get the data I need to... I actually need, you know, to display everything around tags. And same goes with Ascini. So why is this fragment masking interesting? So first it helps you to express component data dependency in a co-located way. Now you don't have like fragments that represent like sub-models on the front-end. It actually represents the data and this is what GraphQL has been made for, is to be very declarative about data dependency in general, but not only at the query level, also at the component level. It prevents leaking data between components. So you're making sure that if one component is responsible for one thing, which is like displaying the title, it does not get access to other types of data, which could lead to wrong implementation. And the good thing is that if you start doing that, if you start to define fragments to describe components, you're making your UI future-proof for deferred usage. And I'm not talking about that today, but you can already start using defer if you're using Apollo with Apollo Router, but also if you're using Apollo or Yocl with GraphQL Yoga or GraphQL Server Library.