GraphQL-SDL pasten, fertige TypeScript-Types kriegen
Du hast SDL vom Backend und brauchst TypeScript-Types auf dem Client. Kein Apollo-Codegen-Setup, kein Config-File, keine CI-Plugins. Schema links pasten, fertige `schema.types.ts` rechts kriegen, kopieren oder runterladen, ins Projekt droppen.
Der Generator wandert den AST des geparsten Schemas (wir nutzen das offizielle `graphql`-Paket, dasselbe wie Apollo und Yoga), versteht also jedes Konstrukt: `type`, `interface`, `enum`, `union`, `input`, `scalar` und nullable vs non-nullable !. Listen werden in `Array<T>` gewrappt, Input-Type kriegen ihr eigenes TS-Interface (wir halten den `UserInput`-Stil, damit es nicht mit `User` kollidiert).
Alles läuft in Node auf deiner Seite (ein Next.js-Route-Handler) und das Schema verlässt deine Infrastruktur nie an einen Dritten.
So nutzt du das Tool
- GraphQL-SDL ins linke Panel pasten. Der Default-Sample enthält `type User`, `input UserInput` und `enum Status`, damit du die Output-Form sofort siehst.
- `interface` über `type` wählen. `interface` ist näher daran, wie Teams Typen von Hand schreiben, unterstützt Declaration-Merging und `extends`. `type` ist besser für Schemas mit vielen Unions oder Mapped-Types.
- "JSDoc aus Beschreibungen" anschalten, wenn dein Schema `"""field description"""` über Feldern hat. Der Generator schreibt sie als JSDoc über das TS um, sodass deine IDE Tooltips beim Hover zeigt.
- Nullable-Stil wählen: `T | null` (lesbarster, keine Imports) oder `Maybe<T>` (ein Alias-Helper, passt zu Apollo Codegen). Das Scalar-Map funktioniert für beide gleich.
- "Connection / Edge / PageInfo" anschalten, wenn dein Schema das Relay-Pagination-Pattern nutzt. Der Generator ergänzt generische `Connection<T>`, `Edge<T>` und `PageInfo` oben in der Datei.
- Scalar-Map editieren, um deine Custom-Scalars zu mappen: `DateTime -> string` (am häufigsten, Server liefert ISO 8601), oder `Date -> Date`, wenn der Client deserialisiert, `JSON -> Record<string, unknown>`, `BigInt -> string` (sicherer als `bigint` mit JSON).
- "Copy" drücken, um das Ergebnis im Clipboard zu haben, oder "Download", um es als `schema.types.ts` zu speichern. In dein Projekt pasten, Typen importieren, fertig.
Wann das nützlich ist
Fünf Situationen, in denen dir der Generator eine Stunde Codegen-Setup spart:
- Kleines Projekt, kein Apollo Codegen. Apollo Codegen / GraphQL Code Generator sind mächtig, brauchen aber Config-Files, Watch-Modus und Plugin-Installs. Für 20 Typen aus einem Hasura- oder PostGraphile-Schema ist es einfacher, einmal die SDL hier zu pasten, zu generieren, in `types.ts` zu droppen und weiterzumachen.
- Public GraphQL-API adoptieren (GitHub, Shopify, Stripe). Du holst das Introspection-Schema via `graphql-cli get-schema`, pastest die SDL, kriegst die Client-Types sofort. Keine Pipeline-Verdrahtung in deine CI.
- Von REST zu GraphQL migrieren und du hast schon REST-Types, mit denen es nicht knallen soll. Der Generator emittet `UserInput` als separaten Typ (überschreibt `User` nicht), also kannst du beide in einer Datei ohne Kollisionen halten.
- Schema für das Frontend-Team dokumentieren. Frontend-Engineers wollen GraphQL-SDL nicht lernen. Hier Schema pasten, das generierte TS schicken - das andere Team sieht dieselben Typen wie das Backend, aber in der Sprache, die es kennt.
- Test-Mocks bauen. Die hier emitten Interfaces sind ideal für `Factory<User>` in `vitest` / `jest`: du mockst Server-Responses, der Compiler prüft, dass du kein Feld vergessen hast.
Für REST-APIs ist das passende Tool OpenAPI zu TypeScript. Für einmalige JSON-Samples ohne Schema ist JSON zu TypeScript schneller.