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

Rate this content
Bookmark

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!

22 min
08 Dec, 2022

Video Summary and Transcription

Hi, everyone! Today, I'll be discussing the future of GraphQL Code Generator and the new features that enhance the developer experience. Code Gen has evolved significantly since its creation in 2016, from generating simple types to hooks and now to a new feature. It has expanded to support multiple languages and framework-specific plugins. Code Gen is widely used in the GraphQL stack, with 7 million monthly downloads on NPM. The new features include Type Document Node, which allows typing GraphQL operations without hooks, and the Client Preset, an improved version of Type Document Node. The Client Preset provides a seamless developer experience by generating the GraphQL function that returns the proper type document node type to your variable. Another interesting feature is fragment masking, which simplifies the usage of fragments in GraphQL and allows for better understanding of data dependencies within the component tree.

Available in Español

1. Introduction to GraphQL Code Generator

Short description:

Hi, everyone! Today, I'll be discussing the future of GraphQL Code Generator and the new features that enhance the developer experience. Code Gen has evolved significantly since its creation in 2016, from generating simple types to hooks and now to a new feature. It has expanded to support multiple languages and framework-specific plugins. Code Gen is widely used in the GraphQL stack, with 7 million monthly downloads on NPM.

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.

2. Type Document Node and its Benefits

Short description:

Code Gen is widely used on the front end, especially for TypeScript stack, and on the back end with any kind of GraphQL server implementation. While generated hooks and SDK are popular, they come with limitations such as replicating signature changes and an exponential number of options. These drawbacks led to the experiment called Type Document Node, which allows typing GraphQL operations without hooks. Type Document Node provides a perfect integration with clients, offering type checking on variables and results. It is supported by various GraphQL clients in the TypeScript ecosystem.

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.

3. Introduction to the Client Preset

Short description:

CodeGen has evolved to generate more than types and now introduces the Client Preset, an improved version of Type Document Node. Developed as an experiment by Lauren from the Guild, it offers a new developer experience.

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.

4. GraphQL Query Implementation with Apollo Client

Short description:

This is a GraphQL query implementation with Apollo Client that uses the new Client Preset. It provides a seamless developer experience by generating the GraphQL function that returns the proper type document node type to your variable. This integration with Apollo Client and other clients ensures typed data and type-checked variables. The bundle impact is minimal, as only one function is generated and all types are removed at runtime. The Babel plugin can further reduce the impact to zero.

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.

5. Fragment Masking in Codegen

Short description:

Let's discuss fragment masking, a new feature in Codegen that aims to simplify the usage of fragments in GraphQL. Fragment masking is a concept introduced by the Relay Team, which suggests using fragments to represent the different views of our application, i.e., components. Each fragment should represent the data used by a specific component. This allows for better understanding of data dependencies within the component tree. Let's take a concrete example to illustrate this concept. We have a dummy app with a document query and a document view fragment. The main component makes the query and uses the client presets to immediately check for any tag errors. The data specific to this fragment is extracted using a special function generated by GraphQL code gen.

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.

6. Fragment Masking and Component Data Dependency

Short description:

Fragment masking allows expressing component data dependency in a co-located way, preventing data leakage between components and making the UI future-proof for deferred usage.

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.

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
WorkshopFree
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
WorkshopFree
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
WorkshopFree
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.