GraphQL to TypeScript

Why GraphQL schemas and TypeScript types tend to drift apart

A GraphQL API and a TypeScript frontend describe the same data twice: once in the schema's SDL (Schema Definition Language), and again by hand in whatever interfaces a developer writes to represent the response shape. Those two descriptions start out matching and then quietly drift — a field gets added to the schema, a type changes from nullable to required, and the hand-written TypeScript interface doesn't get updated to match, because nothing forces it to. The mismatch usually surfaces later as a runtime bug rather than a compile-time error, since TypeScript can only be as accurate as the types a developer gave it.

Full production setups solve this with a code-generation pipeline that reads a live schema and regenerates types automatically on every change. That's the right long-term answer for an actively maintained API, but it's real infrastructure to set up — a config file, a build step, often a running schema endpoint to introspect. This tool exists for the much more common everyday moment: you have a chunk of SDL in front of you — from documentation, a schema file, or a colleague's message — and you just want the matching TypeScript shape right now, without standing up a pipeline for a five-minute task.

What this converter handles

Object types and input types both become TypeScript interfaces, since structurally they describe the same thing: a named shape with typed fields. GraphQL interface definitions become TypeScript interfaces too, and a type's implements clause becomes a TypeScript extends clause. Enums become a string literal union type by default (matching the convention most GraphQL codegen tools use today), with an option to generate a traditional TypeScript enum instead if that fits your codebase better. Union types map directly to a TypeScript union of the member type names, and a custom scalar declaration produces a type alias — defaulting to string, since that's the most common wire representation, with a comment flagging it as worth double-checking against how that particular scalar is actually serialized.

How GraphQL nullability maps to TypeScript

This is the part that's easy to get wrong by hand, and where a converter earns its keep. In GraphQL, a bare type name like String is nullable by default, and a trailing ! makes it non-null — the reverse of how most people initially expect it to read. This tool follows the same convention most GraphQL codegen tools use: a nullable field becomes optional and explicitly includes null in its type (field?: string | null), while a non-null field is required with no null in its type (field: string). List types follow the same logic one level deeper — [String!]! becomes string[] (a required array of required strings), while [String] becomes (string | null)[] | null (an optional array that may itself contain null entries) — the exclamation marks at each level combine to produce noticeably different TypeScript, which is exactly the kind of detail that's tedious and error-prone to translate by hand across a schema with more than a few fields.

What's out of scope, on purpose

This tool converts type shapes, not the full surface of a GraphQL schema. Field arguments (the parameters on a Query or Mutation field) are ignored, since generating a matching parameter list is a different problem from generating a data shape, and most day-to-day type-checking needs are about the response shape, not the request. Directives (@deprecated, custom ones, and so on) and schema descriptions/comments aren't carried over into the output either. None of this is a technical limitation so much as a deliberate scope choice: keeping the conversion predictable and easy to reason about for the common case, rather than trying to reproduce everything a full build-pipeline tool like GraphQL Code Generator does with a live schema and a resolver-aware plugin system. For an actively maintained production API, that kind of full pipeline is genuinely the better long-term tool — this one is built for the quick, one-off conversion in between.

Common use cases

Frontend developers use it to quickly sketch out local TypeScript types while prototyping against a GraphQL API, without waiting on a codegen pipeline to be wired up. Reviewers use it during a schema design discussion to see at a glance what the resulting client-side types would actually look like, which sometimes reveals an awkward nullability choice before it ships. Developers learning GraphQL use it as a fast way to build intuition for how SDL's type system — nullability, lists, interfaces, unions — maps onto the TypeScript type system they may already know better.