gql.tada project aims to improve the experience of writing and using GraphQL
with TypeScript on the client-side by providing more feedback when writing GraphQL,
and reducing friction between TypeScript and GraphQL.
gql.tada as a project was started to answer the question:
“Why can’t we teach TypeScript to understand the GraphQL query language?”
gql.tada is set up, we write our GraphQL queries in pure TypeScript,
our queries automatically infer their types, and our editor introspects our
GraphQL schema and provides immediate feedback, auto-completion, diagnostics,
and GraphQL type hints.
This all happens on-the-fly in TypeScript.
A demo in 128 seconds
How does it work?
The project currently contains two installable modules:
gql.tada, the package providing typings and the runtime API as a library,
@0no-co/graphqlsp, a TypeScript Language Service plugins for editor feedback and integration.
As you start your editor,
@0no-co/graphqlsp is started as a TypeScript Language Service
plugin, which allows it to integrate with the same process that provides your editor
with type hints, diagnostics, and auto-completions; the TypeScript language server
During this time,
@0no-co/graphqlsp will retrieve your GraphQL schema, find GraphQL
documents and provide added diagnostics and features using your schema information.
It will also output an introspection file for
gql.tada to use.
The GraphQL documents, written with
gql.tada will be parsed — all inside TypeScript
typings — and are combined with the introspection information that
provides to create typings for GraphQL result and variables types.
This means, all we see in our code is the plain GraphQL documents with no annotations or distractions:
How does it compare to other solutions?
Typically, when integrating client-side GraphQL code with TypeScript, other solutions will generate typings files for GraphQL documents.
This means that you’ll need to run a persistent and separate process that watches your TypeScript files, and generates more auto-generated TypeScript files containing your GraphQL types.
This leads to the additional friction of having additional generated files around and causing the TypeScript process to having to watch your files, error on changes, picking up the newly generated files, and updating the checks. In other words, these tools cause a “split” between what TypeScript sees, what you see, and what the code generator sees.
gql.tada instead takes the approach of generating the typings fully in TypeScript to
eliminate this “split experience”, reducing friction. All while writing actual GraphQL
queries, rather than an object-syntax, which is only an approximation of GraphQL queries.
Which GraphQL query language features are supported?
gql.tada supports the entire GraphQL query language syntax, and aims to support all
type features that are relevant to GraphQL clients that support typed GraphQL documents
Currently, the list of supported features is:
- Mapping selection sets mapping to object-like types to TypeScript object types
- Grouping type mappings of possible types for interfaces and unions
@includedirectives switching fields and fragments to be optional
- resolving inline fragment and fragment spreads in documents
- inferring the type of
- resolving types of custom scalars from a configuration
The next page, “Installation”, will show you how to install and set up
The following page, “Writing GraphQL”, will show you how to use
gql.tada and write GraphQL documents with it.