GraphQL to TypeScript Generator
Turn a GraphQL schema into TypeScript interfaces, enums, unions and argument types with exact nullability for lists and inputs. Runs in your browser.
The interactive tool loads here when JavaScript runs.
About this toolWhat is the GraphQL to TypeScript Generator?
The GraphQL to TypeScript Generator reads a schema in SDL and writes matching TypeScript declarations: an interface per object and interface type (with an optional __typename), an enum or string union per GraphQL enum, a union type per GraphQL union, an Args interface for every field that takes arguments, and an interface per input type.
Nullability follows the schema exactly. String! becomes string, a nullable String becomes string | null, [Post!]! becomes Array<Post>, and [Post] becomes Array<Post | null> | null. In input types and arguments, a nullable field or one with a default value is optional (?), because the client may leave it out. Custom scalars become type DateTime = unknown so you can map them to your own type.
This produces schema types, which describe everything the server could return. If you want a type for exactly the fields one query selects, use a codegen tool that reads your operations too; the schema types here are still useful for inputs, enums and shared models.
- Exact nullability for fields, list items and lists
- Interfaces, unions, enums or string unions, inputs and field Args types
- Custom scalars emitted as named unknown types
- Descriptions and @deprecated reasons as JSDoc
- Parses the schema properly; runs in your browser
Updated
How to use the GraphQL to TypeScript Generator
- Paste your schema SDL, or press Load Sample.
- Set the Generation Options: Generate Interfaces (object and interface types), Generate Enums (off gives string unions instead), Add Comments (descriptions become JSDoc) and Export All.
- Press Generate Types. A syntax error is shown with its line and column.
- Copy the output or download it as graphql-types.ts.
Worked examples
Nullable lists and arguments
Input
type Query { user(id: ID!, active: Boolean = true): User }
type User { id: ID! tags: [String]! }Output
export interface Query {
__typename?: 'Query';
user: User | null;
}
export interface QueryUserArgs {
id: string;
active?: boolean | null;
}
export interface User {
__typename?: 'User';
id: string;
tags: Array<string | null>;
}The list is required but its items may be null. active has a default, so the client may omit it.
Enums and inputs
Input
enum Role { ADMIN USER }
input CreateUser { name: String! role: Role = USER }Output
export enum Role {
ADMIN = 'ADMIN',
USER = 'USER',
}
export interface CreateUser {
name: string;
role?: Role | null;
}Turning off Generate Enums would print export type Role = 'ADMIN' | 'USER' instead.
Background and insight
GraphQL and TypeScript disagree on one default. In GraphQL every type is nullable unless marked with !, while in TypeScript a type is non-null unless you add | null. A converter that gets this backwards hides real nulls from the compiler, which is exactly the class of bug types are supposed to catch. Lists add a second layer: the ! inside the brackets is about the items and the ! outside is about the list itself, so [String]! and [String!] mean different things.
Inputs follow slightly different rules from outputs. When a server returns an object, a nullable field is still present in the JSON, just null. When a client sends an input, a nullable field can be omitted entirely, and a field with a default value can be omitted even if it is non-null. That is why input fields use ? and output fields use | null.
Common use cases
Typing a small client
Get model and input types for a script or prototype without setting up a codegen pipeline.
Sharing enums with the frontend
Generate enum or union types so UI code cannot use a value the API does not accept.
Reviewing nullability
Seeing every | null spelled out makes it obvious which fields the schema allows to be missing.
Migrating REST types
Compare generated GraphQL types with your existing TypeScript models during a migration.
Tips and limitations
- Map custom scalars yourself: replace unknown with string for DateTime if your server sends ISO strings.
- String unions (Generate Enums off) are often easier to use with JSON data than TypeScript enums, and they add no runtime code.
- Generated object types include every field. Responses only contain the fields you selected, so do not assume all properties are present on query results.
- extend type definitions are merged into the base type before generating.
- For projects with many queries, a build-time tool such as GraphQL Code Generator keeps types in sync with your operations automatically.
Sources and further reading
- Schemas and Types, GraphQL Foundation. Non-null and list modifiers, and how they combine
- GraphQL Specification, October 2021 edition, GraphQL Foundation. Input coercion, default values and nullability
- Everyday Types, TypeScript. Union types, null and optional properties
- Enums, TypeScript. Enums compared with string unions
Frequently asked questions
How are nullable GraphQL fields converted to TypeScript?
A nullable output field becomes T | null and stays required, because the server always sends the key. A nullable input field or argument becomes optional with ?: T | null, because the client may omit it. Fields with ! are plain T.
What does [String!]! become in TypeScript?
Array<string>. The inner ! makes each item non-null and the outer ! makes the list itself required. [String]! becomes Array<string | null>, [String!] becomes Array<string> | null, and [String] becomes Array<string | null> | null.
How are custom scalars like DateTime typed?
Each custom scalar becomes a named type alias set to unknown, for example export type DateTime = unknown. Change it to the type your server actually sends, such as string for ISO dates, and every field using it updates.
Should I use TypeScript enums or string unions for GraphQL enums?
String unions are lighter: they produce no runtime code and accept plain strings from JSON. TypeScript enums give you a named object to iterate over. Turn off Generate Enums to get unions.
Does this generate types for my queries?
No, it generates types for the schema. Query result types depend on which fields each operation selects and on aliases, which needs your operation documents as input. GraphQL Code Generator with the typescript-operations plugin does that.
Is there an in-depth guide to the GraphQL to TypeScript Generator?
Yes. “GraphQL Schemas and Queries: Validation, Types and Query Cost” covers the background, how it works, common pitfalls and worked examples. Read the full guide.
Related Tools You May Like
Free, in-browser tools that pair well with this one.