gql.tada: GraphQL query types inferred in the TypeScript type system

What gql.tada solves for TypeScript GraphQL clients

Hand-written TypeScript types for GraphQL responses drift. You add a field to a query, the response type still describes the old shape, and the compiler stays quiet until something breaks at runtime. Code generation tools fix that by emitting a types file, but the file is a build artifact: it is stale between runs and it is one more thing to keep in sync.

gql.tada takes a different route. Its README describes it as a "GraphQL document authoring library, inferring the result and variables types of GraphQL queries and fragments in the TypeScript type system." The types are not generated into a file you import. They are computed by the type checker from the document literal itself, which is why the README says the result is "always accurate" while you edit. The audience is narrow and specific: TypeScript teams that write GraphQL operations as template literals in source files and want the compiler, not a separate codegen step, to be the source of truth.

How the type inference actually works

The README lists four steps. gql.tada parses your GraphQL documents in the TypeScript type system; it uses your introspected schema and scalar configuration to derive a schema; it maps queries and fragments against that schema to produce result and variables types; and it creates fragment masks, enforcing that fragments are unwrapped gradually.

Two parts of that deserve attention. The schema is not fetched at runtime. It is introspected ahead of time and turned into TypeScript types that the checker can read, which is why the project ships a CLI. The scalar configuration matters for the same reason: a custom scalar has no inherent TypeScript representation, so you tell gql.tada what type to use, and the inference has something concrete to substitute.

Fragment masking is the design decision with the most day-to-day impact. Rather than spreading a fragment's fields into the parent result type, gql.tada keeps the fragment's data masked and requires you to unwrap it. That is stricter than many teams expect from a GraphQL client, and it is deliberate: it stops a component from reading fields it never declared a dependency on.

Installing gql.tada and running the schema step

The README points to the "Get Started" section's Installation page in the documentation for the full procedure, and the repository ships a bin entry named gql.tada. The package is published on npm, so installation starts there.

npm install gql.tada

After installing, the schema has to be introspected and written out so the type checker has something to infer against. The project's own CLI performs that step, and the documentation includes a page dedicated to generating the schema. The README does not spell out the command's flags, so check the CLI reference before wiring it into a script. Once the schema output exists, you write a document with the gql function and the editor should show inferred result types on the variable. For that feedback to appear, GraphQLSP has to be running in your editor; the README states plainly that gql.tada and GraphQLSP together are what produce "on-the-fly, automatically typed GraphQL documents with full editor feedback, auto-completion, and type hints."

Where gql.tada stops being the right tool

The inference lives in the TypeScript type system, and that is also the boundary. If your operations are .graphql files consumed by a server, a mobile client, or any toolchain that does not run tsc, gql.tada has nothing to offer those consumers. The types exist only where the TypeScript checker runs.

The second constraint is the schema step. Because the schema is derived from an introspection result rather than fetched live, a schema change that has not been re-introspected will not show up in your types. The README describes the pipeline as introspect, derive, map, but it does not document what happens when the introspected schema falls behind the running server. That gap is on you to manage.

Third, custom scalars. The README names scalar configuration as an input to schema derivation. A schema with scalars you have not configured is a schema the inference cannot fully resolve, and the failure will surface as types that are less precise than you expected rather than as an obvious error.

gql.tada compared with GraphQL Code Generator

The obvious alternative is GraphQL Code Generator, which also reads a schema and produces TypeScript types. The difference is where the types live. Code Generator emits a file: you run it, it writes typed document nodes or hooks, and your source imports the result. The types are artifacts, and they are only as fresh as the last run.

gql.tada computes types from the document literal during checking, so there is no generated types file to import and no window in which the artifact is stale. The trade is that the work moves into the type checker. Deeply nested queries become deep type computations, and the README's framing of the whole pipeline as happening "in the TypeScript type system and type checker" is a description of that cost as much as of the benefit.

A second difference is fragment handling. Code Generator's typical output spreads fragment fields into the parent type. gql.tada masks fragments and makes you unwrap them, which changes how components consume data and is a real migration cost if you are moving an existing codebase.

Maintenance, releases, and the MIT licence

The repository is not archived, and the last push was on 2026-09-10. Recent releases include [email protected], @gql.tada/[email protected] and @gql.tada/[email protected], all published on 2026-07-25. The README describes the release process: changesets are added to each pull request, and "Version Packages" pull requests are merged to cut new versions. It also notes that @canary releases on npm are available for previewing merged changes.

That process is worth reading before you pin a version, because the packages version independently. The CLI utilities and the internal package carry their own version numbers, so an upgrade of gql.tada does not automatically mean the CLI moved with it.

The licence is MIT, stated in the repository metadata and shipped as LICENSE.md. MIT is permissive and places few conditions on redistribution, but this is not legal advice; if you are vendoring the code or shipping it inside a product, have your own counsel read the file.

Editorial conclusion

Adopt gql.tada if your GraphQL documents live in TypeScript source files and you have an introspected schema plus scalar configuration to feed it; the payoff is result and variables types that track the schema while you edit. Do not adopt it if your operations live in .graphql files consumed by non-TypeScript tooling, or if you cannot run a schema introspection step in your build. Before committing, verify three things: that the gql.tada CLI can reach your schema and write its output file, that your scalar configuration covers every custom scalar your queries touch, and that your editor is running GraphQLSP, because without it the type feedback the README promises does not appear.

Frequently asked questions

Official sources

1. 0no-co/gql.tada on GitHub
2. License: MIT
3. Project website
4. README
5. Releases