GraphQL zu TypeScript & Codegen

GraphQL zu TypeScript & Codegen

Konvertieren Sie GraphQL-SDL-Schemas und Queries in TypeScript-Typen, Interfaces, Enums und Resolver. Direkte browserbasierte Codegenerierung ohne Server-Upload.

Vorlagen
Codegen-Ziel-Ökosystem
GraphQL-Schema-Quelle (SDL / JSON-Introspektion)
Schnell-Skalare:
Produktionsreifer Export
12Nodes
AST Architecture
Object: 6Interface: 1Enum: 1Input: 1
83%Strict
Nullability Guard

High non-null strictness (safe against unexpected runtime undefined).

Gültiges Schema-AST
/**
 * Strongly Typed GraphQL TypeScript Artifacts
 * Generated via ToolsAA In-Browser Codegen Engine [Regime: strict-modern]
 * 100% In-Browser AST synthesis - Zero server upload
 */

type Maybe<T> = T | null;

type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> };
type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> };

/** All Built-In & Custom GraphQL Scalars */
type Scalars = {
  DateTime: string;
};

type Scalars = {
  JSON: Record<string, unknown>;
};

type Scalars = {
  Money: number;
};

type ProductStatus = 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'OUT_OF_STOCK';

type Node = {
  __typename?: string;
  readonly id: string;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type MoneyAmount = {
  __typename?: 'MoneyAmount';
  readonly amount: number;
  readonly currency: string;
};

type ProductVariant = {
  __typename?: 'ProductVariant';
  readonly id: string;
  readonly sku: string;
  readonly title: string;
  readonly price: MoneyAmount;
  readonly inStock: boolean;
  readonly inventoryQuantity: number;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type Review = {
  __typename?: 'Review';
  readonly id: string;
  readonly author: string;
  readonly rating: number;
  readonly comment: Maybe<string>;
  readonly metadata: Maybe<Record<string, unknown>>;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type Product = {
  __typename?: 'Product';
  readonly id: string;
  readonly title: string;
  readonly slug: string;
  readonly description: Maybe<string>;
  readonly status: ProductStatus;
  readonly price: MoneyAmount;
  readonly variants: ReadonlyArray<ProductVariant>;
  readonly reviews: ReadonlyArray<Review>;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type Query = {
  __typename?: 'Query';
  readonly product: Maybe<Product>;
  readonly products: ReadonlyArray<Product>;
};

type Mutation = {
  __typename?: 'Mutation';
  readonly createProduct: Product;
  readonly deleteProduct: boolean;
};

type CreateProductInput = {
  readonly title: string;
  readonly slug: string;
  readonly description?: Maybe<string>;
  readonly price: number;
  readonly currency?: Maybe<String = "USD">;
  readonly status?: Maybe<ProductStatus = DRAFT>;
};
Typen12
Felder40
Enums1
Unions0
Skalare3
Geparst in< 1ms
Technische Referenz & Architektur-Leitfaden

GraphQL TypeScript Generator & Codegen — Referenzhandbuch

Konvertieren Sie GraphQL-Schema-SDL und Queries in TypeScript-Typen, Interfaces, Enums und Resolver. Sofortiges clientseitiges Codegen ohne Konfiguration oder Server-Upload.

GraphQL TypeScript Generator & Codegen — Referenzhandbuch — Client-seitige In-Memory-Architektur und Datenfluss
GraphQL TypeScript Generator & Codegen — Referenzhandbuch — Client-seitige In-Memory-Architektur und Datenfluss

Wichtige Parameter & Einstellungen

GraphQL-Schemaquelle (SDL vs. Introspection-JSON)Schema-Definitionsdokument (AST-Eingabe)

Standardmäßiger Text in der GraphQL Schema Definition Language (SDL) oder serialisierte JSON-Introspection-Antwort (__schema-Wurzelobjekt). Entspricht der offiziellen GraphQL-Spezifikationsgrammatik vom Oktober 2021.

Standard: Schema Definition Language (SDL)
Nullability- & OptionalitätsstrategieCompiler-Nullability-Modus (Enum)

Bildet Nicht-Null-Felder (!) und Nullable-Felder von GraphQL auf TypeScript-Typausdrücke ab. Steuert, ob für nullable Felder 'T | null', 'Maybe<T>' oder optionale Eigenschaften 'field?: T' unter strictNullChecks erzeugt werden.

Standard: Maybe<T> = T | null | undefined
Typdeklarations-ParadigmaTyp-Ausgabesyntax (Enum)

Legt fest, ob GraphQL-Objekttypen zu TypeScript-'type'-Aliassen oder 'interface'-Deklarationen kompiliert werden. Typ-Aliasse unterstützen indizierte Zugriffe und Unions; Interfaces ermöglichen Declaration Merging in erweiterbaren SDKs.

Standard: type (Typ-Aliasse)
Enum-KompilierungsformatEnum-Repräsentation (Enum)

Steuert, ob GraphQL-Enums zu nativen TypeScript-'enum'-Laufzeitobjekten oder Tree-Shaking-fähigen String-Literal-Unions ('ADMIN' | 'USER') mit begleitenden const-Dictionaries kompiliert werden.

Standard: String-Literal-Union
Benutzerdefiniertes Skalar-Typ-Mapping (ScalarMappingDictionary)Dictionary (Record<string, string>)

Löst benutzerdefinierte GraphQL-Skalare in konkrete TypeScript-Typen auf. Standard-Mappings: ID zu 'string', Int zu 'number', Float zu 'number', String zu 'string', Boolean zu 'boolean', DateTime zu 'string | Date'.

Standard: DateTime: string, JSON: Record<string, unknown>
Unveränderlicher / Readonly-Array-ModifikatorImmutability-Flag (Boolean)

Fügt bei Aktivierung den Modifikator 'readonly' in jedes Objektfeld ein und kapselt alle Listen in 'ReadonlyArray<T>', um strikte Compile-Time-Unveränderlichkeit in Redux- und Zustand-State-Stores zu erzwingen.

Standard: true

Profi-Tipps & Best Practices

Universelle Nullability-Falle: GraphQL-Nullable-Felder vs. TypeScript-Undefined

In GraphQL gibt ein nullable Ausgabefeld ohne Ausrufezeichen explizit null zurück, wenn es nicht befüllt ist, niemals undefined. In TypeScript erlaubt die Deklaration 'field?: string' zwar undefined, weist jedoch unter strictNullChecks explizites null ab. Erzeugen Sie für Client-Antworttypen stets 'field: Maybe<string>' (string | null) anstelle von 'field?: string', um Laufzeit-TypeError-Exceptions beim Zugriff auf Server-Payloads mit null-Werten zu verhindern.

Native numerische Enums vermeiden: String-Literal-Unions für Laufzeit-Bundle-Größe von null

Natives TypeScript-'enum' erzeugt ein zweiseitiges JavaScript-IIFE-Laufzeitobjekt, das von modernen Bundlern (Vite, Rollup, esbuild) nicht per Tree-Shaking entfernt werden kann. In Client-Anwendungen eliminiert die Generierung von 'type UserRole = "ADMIN" | "MEMBER"' in Kombination mit einem per 'as const' eingefrorenen Array den Laufzeit-Overhead zu 100 %, bietet jedoch identische Autovervollständigung und präzisere Typverengung.

Fragment-Maskierung mit TypedDocumentNode statt generischer Query-Wrapper

Erzeugen Sie anstelle monolithischer Query-Ergebnistypen und manueller Typzusicherungen für Fetch-Antworten direkt TypedDocumentNode<ResultType, VariablesType>-Instanzen. Moderne GraphQL-Clients (Apollo Client 3.7+, urql und graphql-request) leiten sowohl die Datenstruktur als auch die erforderlichen Variablen automatisch direkt aus dem Document-Node ab – ganz ohne explizite Typparameter.

Serialisierungs-Transporttypen von Domain-Modellen im Arbeitsspeicher trennen

Benutzerdefinierte Skalare wie DateTime, JSON und BigInt werden über das Netzwerk als JSON-Strings oder primitive Zahlen übertragen. Wenn Ihr Codegen 'DateTime' auf JavaScript-'Date' mappt, belässt ein standardmäßiges JSON.parse() das Feld als String. Dies führt zu Laufzeitfehlern bei Datumsmethoden (z. B. date.toISOString() is not a function). Verwenden Sie 'string' für Wire-Antworttypen und reservieren Sie 'Date' für geparste Domain-Modelle oder Deserialisierungs-Transformer.

Häufige Fehlerquellen & Fehlerbehebung

⚠️TypeScript-Compilerfehler TS2322: Type 'null' is not assignable to type 'undefined' bei generierten Input-Objekten

GraphQL-Input-Objekte behandeln weggelassene Felder als undefined, während ein explizites null ein gezieltes Zurücksetzen signalisiert. Aktivieren Sie exactOptionalPropertyTypes in der tsconfig.json und konfigurieren Sie die Codegen-Eingabestrategie so, dass für Eingabeargumente 'field?: string | null' ausgegeben wird, um zwischen dem Weglassen eines Schlüssels und dem Übergeben einer expliziten null-Payload sauber zu unterscheiden.

⚠️Zirkuläre Referenztiefe überschreitet TypeScript-Compiler-Limits bei tief verschachtelten rekursiven Schemas

Selbstreferenzierende Schemastrukturen (wie Comment -> replies: [Comment!]! oder Category -> children: [Category!]!) können die unendliche Typinstanziierung TS2589 auslösen. Beheben Sie dies, indem Sie Typdefinitionen als 'interface'-Deklarationen statt als geschachtelte rekursive 'type'-Aliasse ausgeben, wodurch die verzögerte Eigenschaftsauflösung (Lazy Evaluation) von TypeScript-Interfaces genutzt wird.

⚠️Syntaxfehler: Unexpected token in JSON at position 0 beim Einfügen von Introspection-Ergebnissen

Stellen Sie sicher, dass Sie die gesamte JSON-Payload einfügen, die den Wurzelschlüssel '__schema' oder 'data.__schema' enthält. Falls die Introspection-Query über curl oder Postman abgerufen wurde, entfernen Sie HTTP-Antwort-Header oder maskierte Anführungszeichen vor dem Parsen.

⚠️Apollo-Federation-Direktiven (@key, @external, @shareable) verursachen Parser-Fehler wegen unbekannter Direktiven

Der Standard-Parser der GraphQL-Spezifikation enthält standardmäßig keine Apollo-Federation-v1/v2-Schemadirektiven. Der Generator verfügt über integrierte Federation-Direktiven-Stubs. Stellen Sie sicher, dass die Option 'Federation-Direktiven aktivieren' eingeschaltet ist, oder fügen Sie den standardmäßigen Definitionsblock für Federation-Direktiven am Anfang Ihres SDLs ein.

Häufig gestellte Fragen (FAQ)

Wie wird GraphQL-Nullability auf optionale TypeScript-Felder im Vergleich zu Null-Unions abgebildet?▼

In GraphQL SDL sind Felder standardmäßig nullable und nur dann non-null, wenn sie mit einem Ausrufezeichen (!) versehen sind. In TypeScript unter strictNullChecks werden Non-Null-Felder (String!) zu 'string' kompiliert, während Nullable-Felder (String) zu 'string | null' (oder 'Maybe<string>') werden. Bei Input-Objekten werden Nullable-Felder zu optionalen Eigenschaften ('field?: string | null'), da GraphQL das Weglassen von Argumenten in Queries und Mutationen ausdrücklich erlaubt.

Sollten GraphQL-Enums in TypeScript-Enums oder String-Literal-Union-Typen umgewandelt werden?▼

String-Literal-Unions ('type Status = "ACTIVE" | "INACTIVE"') werden für moderne Webanwendungen empfohlen, da sie zu null Byte JavaScript-Laufzeitcode kompilieren, sich perfekt per Tree-Shaking optimieren lassen und reine String-Literale ohne Enum-Importe akzeptieren. Native TypeScript-Enums ('enum Status { Active = "ACTIVE" }') sollten nur gewählt werden, wenn Laufzeit-Objekt-Reflektion, Reverse-Lookups oder die Integration mit Legacy-Bibliotheken erforderlich sind.

Was ist der Unterschied zwischen Schema-Types-Codegen und Client-Operation-Types-Codegen?▼

Schema-Types-Codegen kompiliert das gesamte GraphQL-Backend-Schema (jeden Typ, jeden Input, jedes Enum und jede Resolver-Signatur) in umfassende TypeScript-Interfaces. Client-Operation-Types-Codegen analysiert hingegen spezifische Client-Query-Dokumente, selektiert ausschließlich die abgefragten Unterfelder (unter Anwendung von Selection Sets und Fragmenten) und erzeugt flache, präzise Antworttypen, die exakt der von dieser Abfrage zurückgegebenen JSON-Payload entsprechen.

Warum serialisiert der GraphQL-Skalar ID zu string oder number statt zu einem dedizierten TypeScript-Typ?▼

Die offizielle GraphQL-Spezifikation definiert den ID-Skalar als eindeutigen Bezeichner, der als String serialisiert wird, erlaubt Clients jedoch die Übergabe von String- oder Integer-Werten als Eingabe. Folglich mappt der TypeScript-Codegen ID auf 'string' (für Ausgabetypen) oder 'string | number' (für Eingabeargumente). Anwendungen, die Typsicherheit zwischen verschiedenen Entitäts-IDs benötigen, sollten Branded Types (z. B. 'type UserId = string & { readonly __brand: unique symbol }') verwenden.

Verwandte Tools & Hilfsprogramme

Alle Tools →