GraphQL Galaxy

GraphQL Galaxy 2022

<p><span>GraphQL Code Generator v3 brings the easiest and most lightweight way to get typed GraphQL in your front-ends by only generating types. In this talk, we will see that generating GraphQL types has never been so easy!</span></p>

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 CodeGen for the last six months, and especially working on the feature I'm going to showcase today and on the upcoming roadmap for CodeGen. So before looking at this new developer experience that CodeGen is bringing, let's take a look at the history of CodeGen and how we went from generating simple type to hooks to the new feature that we're going to see today. So CodeGen 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 CodeGen before 1.0 was just generating plain TypeScript types. Then a bit later on, CodeGen started to bring support for generating types to many types of languages beyond TypeScript and JavaScript, such as Java, C Sharp, but also Kotlin, et cetera. And a bit later on, again, due to high demand on the frontend, CodeGen started to generate like framework specific plugins, such as Apollo Client, Yorkle, Vue, Angular, and so on. CodeGen 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, so CodeGen is very famous on the frontend side, especially for TypeScript stack, but also on the backend with TypeScript stack, but any kind of GraphQL server implementation. And if we look closer on the frontend, because this is the subject of today, we're going to talk about a new experience on the frontend. We'll see that nowadays people are very, very happy with generated hooks in SDK. So while generated hooks in SDK are very famous, we took a step back and looked at also the drawbacks that comes with this such an approach. First, the limitation of hooks in SDK that are generated by CodeGen are first replicating signature changes. So since CodeGen now is responsible of wrapping a lot of libraries on the frontend, like React, Query, Apollo, Yorkle in React, but Yorkle in Vue, Apollo Angular, et cetera, et cetera. 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 library, we are providing access to the underlying specific options of each library and we are staying aligned with the different like major version. 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 CodeGen itself has a lot of options to make it more tailored, more configurable, and very 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 CodeGen 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 option is not going to break 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 frontend and web application where bundle performance and bandwidth impact is very important. And CodeGen, when generating wrappers such as EZK, 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 TypeDocumentNode. So TypeDocumentNode, it's an experiment that started in 2020. And it started with a simple question. What if we could type GraphQL operation 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 a product on a given currency. And 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, or 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 GraphQL clients. 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 typed result. So here is the data is typed properly with the right query type from TypeScript operations, and same with subproperties. So this has been made possible because Dottan 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 frontend TypeScript ecosystem. You can already use TypeDocumentNode with Apollo Client, ReoCore, Preact, React Query, even with the VR, and you can use also in Svelte, Vue, et cetera. So here we can see that the vision it brought is that first code gen has been created to 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 like better and 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 TypeDocumentNode. TypeDocumentNode is a stable way of using it, but now we are bringing an improved version of TypeDocumentNode that has been developed first as an experiment by Lauren from the Guild, and now it's been released as a stable plugin from CodeJet. And this new feature is called the Client Preset. So this is a GraphQL query implementation with Apollo Client that use 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 a GraphQL function that has been generated for you by CodeGen in the same way that you import GQL when you are using Oracle or Apollo Client. And the thing here is that this GraphQL function that we provide you is going to return the proper TypeDocumentNode type to your variable depending on the query that you are passing to it, which means that as just showcased with TypeDocumentNode here, by just using this GraphQL function to define your operation, this document variable is going to be typed, is going to carry the type of the query and the variable, and is perfectly integrated with Apollo Client and all the other clients as just showcased. So your data is going to be typed and your variables 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 CodeGen in watch mode, your GraphQL operation gets 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. And if you really want to have like a zero bundle 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 brought 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 are 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 like 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 from the ecosystem. So this new feature of CodeGen is trying to bring you a way of using fragment masking 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 subtypes of existing types so you can actually pass them in your component, et cetera, et cetera. 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 assignee is one component, and the tags is also a dedicated child 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 RelayTeam, 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. By views, we say components. So each fragment should represent which data is used by a component. Let's put that into practice. Here we have the same query, but we changed it. Since we have one component for a 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 are going to really express what are the data dependencies of our child component. So we have the dog view, which instantiates the assignee. We display the title, instantiate the assignee, and the tags. And each subcomponent 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 Code Jam. 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, but it's 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 component. 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 assignable 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, OK, we are in the doc view. So we use a special function that is exposed, generated by GraphQL Code Jam to extract the data that is specific to this fragment, which is the fragment of our top component, which is the 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 its 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 collocation. 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. And here, you can see that I only get the data I actually need to display everything around tags. And same goes with Ascini. So why this fragment masking is interesting? So first, it helps you to express component data dependency in a collocated way. Now, you don't have like fragment that represent like submodels 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 of one thing, which is like displaying the title, it does not get access to other type of data, which could lead to wrong implementation. And the good thing is that if you start to do 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 Yoql with GraphQL Server Yoga or GraphQL Server Library. Okay. So let's now talk about the future of CodeGen. So as we just saw, there is ongoing work about the v3 of CodeGen. The first step has been to bring a better developer experience with this client preset, as we just saw, which works with types of light bundling pack or zero bundling pack if you use like the bundle plugin and brings you like a very tight as you type GraphQL operation. Then we moved all the other existing front-end plugins like hook generation, SDK generation to a community plugin repo where all the community is going to be able to maintain by themselves using GitHub code owner and making sure that the community is going to be able to continue to grow by itself with all help, but not with us as a blocker to make it to enable moving forward on all those plugins. Also this is, so all those three first points are already happening. Right now you can, as I just showcased, you can use a CodeGen config in TypeScript and get type config. So this brings you a superior experience because now if you make a typo in your config, you're going to have TypeScript error and you're going to have TypeScript auto-completion. In the upcoming months, we're going to start rewriting the core of CodeGen, so the core package to have more performance, a smarter watch and fewer types generated to actually only generate types that are being used in operation. And finally, we plan to introduce support for modern GraphQL features such as different stream and other like RFCs on GraphQL. We are waiting for your feedback and we need your feedback on this roadmap proposal and this roadmap we are starting to iterate on. There is an issue dedicated to that that is pinned at the top of issues on the main GraphQL CodeGen repo. So we are waiting for your feedback and we are building this v3 with you together. So like I just said, this presentation was about GraphQL CodeGen. The Guild is doing a lot of things in the GraphQL ecosystem. We are building our own gateway library with GraphQL Mesh, our own GraphQL server implementation, which brings a lot of features for modern API, especially future-proof GraphQL API with Envelope. We still have GraphQL Module, GraphQL Scalar. We just launched our first GraphQL registry, SASS, which is open source, GraphQL Hive. You can go on our blog. We have a lot of articles that we publish very frequently, and especially we have some articles that explain this fragment masking concept in detail. Thank you very much.
