Home/Developer, Code & Web Engineering Tools/GraphQL to TypeScript Generator

GraphQL Query to TypeScript Typed Document Node Generator

Compile GraphQL queries and schemas directly into strongly-typed TypeScript interfaces, variables, and TypedDocumentNode definitions online.

Quick Templates:
Executable AST Document
Target Config & Type Definitions
Compiled TypeScript Definitions
/*
 * Generated by TwisterTools 2.0 - TypedDocumentNode Generator
 * Target: typed-document-node | Mode: strict-null
 * Safe, deterministic, zero-runtime overhead.
 */

import { type TypedDocumentNode } from "@graphql-typed-document-node/core";

// GraphQL Enums
export type Role =
  | "USER"
  | "ADMIN"
  | "EDITOR";

export type GetUserProfileVariables = {
  readonly userId: string;
};

export type GetUserProfileData = {
  readonly userById: {
    readonly id: unknown;
    readonly name: unknown;
    readonly email: unknown;
    readonly role: unknown;
  };
};

export const GetUserProfileDocument: TypedDocumentNode<GetUserProfileData, GetUserProfileVariables> = {
  kind: "Document",
  definitions: [
    /* Ast definitions pre-parsed for zero runtime cost */
    { kind: "OperationDefinition", operation: "query", name: { kind: "Name", value: "GetUserProfile" } }
  ]
} as unknown as TypedDocumentNode<GetUserProfileData, GetUserProfileVariables>;
TypeScript 5.x ReadyZero Bundler Overhead

The Architecture of TypedDocumentNode in Modern GraphQL Clients

GraphQL operations are fundamentally dynamic text queries transformed into AST objects at runtime. Traditionally, linking query responses and variable parameters to TypeScript types required repetitive manual generic typing or complex build-step watchers. TypedDocumentNode solves this by embedding return types directly into the AST structure itself.

Exact Return Typing

By typing both the response payload and variable definitions within the AST token, hooks like Apollo's useQuery(document) infer shape without explicit generics.

Compile-Time Safety

Invalid variable arguments or access to unselected GraphQL fields are caught instantly during tsc compilation rather than bubbling into production runtime errors.

Zero Runtime Overhead

Because TypedDocumentNode uses Phantom Types (types that only exist at compile time), the compiled JavaScript footprint is identical to a standard document AST.

Comparative Analysis: Client-Side Typing Strategies

MethodType SafetyBuild SetupDeveloper ErgonomicsIdeal Scenario
TypedDocumentNodeComprehensiveZero / MinimalAutomatic inference in hooksModern React, Next.js, and SSR microfrontends
Manual Generic HooksPartial / Error-proneNoneHigh repetition (userQuery<T, V>)Legacy prototypes or rapid proofs of concept
CLI Codegen (Watchers)ComprehensiveHeavy (Node CLI + Plugins)Full schema synchronizationMassive monorepos with hundreds of fragments

Frequently Asked Questions (FAQ)

What is TypedDocumentNode and how does it improve type safety?

TypedDocumentNode is a TypeScript type wrapper around standard GraphQL AST DocumentNode objects. By pairing the document node with generic parameters for query results and variables (<TResult, TVariables>), client libraries like Apollo Client, Urql, and GraphQL-Request automatically infer returned data structures and variable requirements without manually typing hook or client calls.

Why should teams prefer client-side type generation over heavyweight build-step codegen?

While large CLI tools like GraphQL Code Generator are excellent for enterprise CI/CD pipelines, lightweight browser-based generators enable instant prototyping, micro-service mocking, and quick script writing without configuring extensive YAML configs, plugins, and dependencies.

How does this generator handle custom scalars like DateTime or JSON?

Custom scalars can be mapped through the custom scalars configuration panel. By standardizing unknown GraphQL scalar strings into defined TypeScript types (such as string, Date, or Record<string, unknown>), your downstream code preserves full semantic safety.

Does this utility support mutation and subscription operations?

Yes. The parser identifies query, mutation, and subscription declarations. It automatically maps the selection tree back to the corresponding root schema type (Mutation or Subscription) and formats variables accordingly.

What is the advantage of using readonly and immutable TypeScript properties?

Applying readonly modifiers prevents inadvertent mutations to cache entries, query results, and UI parameters. Modern state managers like Apollo In-Memory Cache and Urql normalize entities immutably; readonly types guarantee compile-time enforcement of cache integrity.

Is my GraphQL schema or query uploaded to an external server?

No. All parsing, schema traversal, and TypeScript token synthesis are performed entirely within your browser using modern client-side execution. No proprietary schemas or query documents ever touch an external network.

Found this tool helpful? Share it with others!

Share on Facebook
Share on X
Share on LinkedIn

Related & Complementary Utilities

Explore more privacy-first client-side web tools.