TypedDocumentNode: the next generation of GraphQL and TypeScript
Tags: graphql, codegen, typescript, react
Published: 2021-07-29 10:05:21

> This article was published on Wednesday, July 22, 2020 by [Dotan Simha](https://twitter.com/dotansimha) @ [The Guild Blog](https://the-guild.dev/)

// Examples are in: https://codesandbox.io/s/quizzical-browser-1em9r?file=/index.ts**Using GraphQL and Typescript on the client just became a lot easier!**The [GraphQL Code Generator](https://graphql-code-generator.com) project has been around for 3
years, and we are constantly keep working on it and listening to your feedback!As we were working and thinking about
[the next major version of the codegen](https://github.com/dotansimha/graphql-code-generator/discussions/3955),
we came up with a really awesome tool which didn't require any breaking change!So today, after successfully integrating this feature into few of our largest clients, we can
proudly share it with you -
[`TypedDocumentNode`](https://github.com/dotansimha/graphql-typed-document-node).A new and easier way to enjoy and integrate GraphQL and Typescript on the client.`TypedDocumentNode` is a development tool for creating fully typed `DocumentNode` objects. It means
that just by passing the GraphQL query/mutation/subscription/fragment to a supporting GraphQL client
library, you'll get fully-typed result and variables objects.This is made possible by
[TypeScript type inference](https://typescriptlang.org/docs/handbook/type-inference.html).## TL;DR*   [`TypedDocumentNode`](https://github.com/dotansimha/graphql-typed-document-node) is a great
    solution for having pre-compiled (`DocumentNode`) GraphQL operations with built-in support for
    TypeScript types.
*   No need to specify types manually in your application code, all types are inferred automatically
    from your operation object.
*   You can easily extend any GraphQL client library to support it, even without changing the library
    code.
*   You can integrate it to your project
    [using these instructions](https://github.com/dotansimha/graphql-typed-document-node#how-to-use)<Video src="https://youtube.com/embed/cYIhx8dusa4" title="Typed Document Node with GraphQL Code Generator" />## Client-Side Applications, TypeScript and GraphQLThe integration of GraphQL and TypeScript in client-side applications has evolved in recent times:### 2016: Manual TypingsWe started with manually writing TypeScript types for our operations. It worked, but it didn't
scale. It needed maintenance to make sure our types matched the exact selection set we are fetching.<img width="100%" style="width:100%" src="https://thumbs.gfycat.com/SphericalLikelyCusimanse-size_restricted.gif" />### 2017: Generated TypesWe moved to generated TypeScript types, with the power of
[GraphQL Code Generator](https://graphql-code-generator.com) - using `@graphql-codegen/typescript`
and `@graphql-codegen/typescript-operations` plugins.It's simpler (no need to maintain the types manually) but it requires us to manually specify the
types each time we use the query.<img width="100%" style="width:100%" src="https://thumbs.gfycat.com/ChubbyFrigidArgentinehornedfrog-size_restricted.gif" />### 2018: Generated CodeThe next step of that evolution was to generate code - that means that we can generate React Hooks
(`@graphql-codegen/typescript-react-apollo` or `@graphql-codegen/typescript-urql`), Angular Services
(`@graphql-codegen/typescript-apollo-angular`) and much more. We can even generate a pre-compiled
`DocumentNode` instead of dealing with Webpack loaders.This generated code takes GraphQL and TypeScript to the next level - because we are getting
ready-to-use code that has TypeScript types built-in and allow us to use it directly from our
application code without the need to specify the types or GraphQL document manually:<img width="100%" style="width:100%" src="https://thumbs.gfycat.com/PastFatalIrishwaterspaniel-size_restricted.gif" />### 2020: New `TypedDocumentNode`Generating code is nice, but we don't always need to wrap hooks, services or similar code with more
code. With the power of TypeScript, we can pre-compile the GraphQL operation into a `DocumentNode`,
and add burn-in the TypeScript types.With the support of the client-side libraries, we get automatic type inference and auto-complete -
without generating additional code:<img width="100%" style="width:100%" src="https://thumbs.gfycat.com/JoyfulAbleAsianwaterbuffalo-size_restricted.gif" />## Live Demo[You can try it live here](https://codesandbox.io/s/github/dotansimha/graphql-typed-document-node/tree/master/examples/apollo-client-3);
note the autocomplete and automatic type inference for the `result` variable.## How Does It Work?This project works in the following way:1.  You write your GraphQL operations (`query` / `mutation` / `subscription` / `fragment`) in any way
    your prefer (for example - in a `.graphql` file).
2.  [GraphQL Code Generator](https://graphql-code-generator.com) will generate a `TypedDocumentNode`
    for your operations (which is a bundle of pre-compiled `DocumentNode` with the operation result
    type and variables type).
3.  Instead of using your `.graphql` file, import the generated `TypedDocumentNode` and use it with
    your GraphQL client framework.
4.  You'll get automatic type inference, auto-complete and type checking based on your GraphQL
    operation.The definition of `TypedDocumentNode` is super simple - it's all about the TS generics:```ts
import { DocumentNode } from 'graphql'

export interface TypedDocumentNode<Result = {}, Variables = {}> extends DocumentNode {}
```### Can I Use It Now?This library is already available to use, but it requires you to setup it in your project, since
`TypedDocumentNode` isn't supported automatically in all GraphQL client libraries.That's why we used `patch-package` to patch existing declarations, and added support to other
libraries without effecting it's runtime.[You can find a list of all supported GraphQL clients here](https://github.com/dotansimha/graphql-typed-document-node#supported-libraries)
and
[a short getting started tutorial here](https://github.com/dotansimha/graphql-typed-document-node#how-to-use).If you are using a library that isn't supported yet,
[you can always add support to it manually using method overloading](https://github.com/dotansimha/graphql-typed-document-node#how-to-extend-other-libraries-with-this).## What's Next?GraphQL client libraries
[can easily add support](https://github.com/dotansimha/graphql-typed-document-node#how-can-i-support-this-in-my-library)
for `TypedDocumentNode`, without breaking any API, allowing developers to have direct support for
that, without the need for the supporting libraries.And, maybe, one day, it will part of the
[original GraphQL `DocumentNode` interface](https://github.com/graphql/graphql-js/blob/4b7ab47c3f4ea6be99c3d9754b21fe626f7c7177/src/language/ast.d.ts#L212-L216)
;)