Collez du SDL GraphQL, obtenez des types TypeScript prêts
Vous avez un SDL venu d'un backend et il vous faut des types TypeScript côté client. Pas de setup Apollo Codegen, pas de fichier de config, pas de plugins CI. Collez le schéma à gauche, obtenez un `schema.types.ts` prêt à droite, copiez ou téléchargez, déposez dans votre projet.
Le générateur parcourt l'AST du schéma parsé (nous utilisons le package officiel `graphql`, le même qu'utilisent Apollo et Yoga), il comprend donc chaque construction : `type`, `interface`, `enum`, `union`, `input`, `scalar`, et le nullable vs non-nullable !. Les listes sont enveloppées dans `Array<T>`, les input type reçoivent leur propre interface TS (nous gardons le nom de style `UserInput` pour ne pas entrer en collision avec `User`).
Tout tourne en Node de votre côté (un route handler Next.js) et le schéma ne quitte pas votre infrastructure pour un tiers.
Mode d'emploi
- Collez le SDL GraphQL dans le panneau de gauche. L'exemple par défaut inclut un `type User`, un `input UserInput` et un `enum Status` pour que vous voyiez immédiatement la forme de la sortie.
- Choisissez `interface` plutôt que `type`. `interface` est plus proche de la façon dont les équipes écrivent les types à la main, prend en charge le declaration merging et `extends`. `type` est meilleur pour les schémas avec beaucoup d'unions ou de types mappés.
- Activez « JSDoc from descriptions » si votre schéma a des `"""description du champ"""` au-dessus des champs. Le générateur les réécrit en JSDoc au-dessus du TS, votre IDE affichera des tooltips au survol.
- Choisissez un style nullable : `T | null` (le plus lisible, sans imports) ou `Maybe<T>` (un alias helper, correspond à Apollo Codegen). La table de scalars fonctionne de la même façon pour les deux.
- Activez « Connection / Edge / PageInfo » si votre schéma utilise le pattern de pagination Relay. Le générateur ajoute des génériques `Connection<T>`, `Edge<T>` et `PageInfo` en haut du fichier.
- Éditez la table de scalars pour mapper vos scalar custom : `DateTime -> string` (le plus courant, le serveur renvoie de l'ISO 8601), ou `Date -> Date` si le client désérialise, `JSON -> Record<string, unknown>`, `BigInt -> string` (plus sûr que `bigint` avec JSON).
- Cliquez sur « Copier » pour mettre le résultat dans le presse-papiers ou sur « Télécharger » pour l'enregistrer sous `schema.types.ts`. Collez-le dans votre projet, importez les types, c'est fait.
Quand c'est utile
Cinq situations où ce générateur vous fait gagner une heure de setup de codegen :
- Petit projet, vous ne voulez pas d'Apollo Codegen. Apollo Codegen / GraphQL Code Generator sont puissants mais exigent fichiers de config, mode watch et installations de plugins. Pour 20 types issus d'un schéma Hasura ou PostGraphile, il est plus simple de coller le SDL ici une fois, générer, déposer dans `types.ts` et passer à autre chose.
- Adoption d'une API GraphQL publique (GitHub, Shopify, Stripe). Vous récupérez le schéma d'introspection via `graphql-cli get-schema`, collez le SDL, obtenez les types client instantanément. Pas besoin de brancher leur pipeline dans votre CI.
- Migration de REST vers GraphQL et vous avez déjà des types REST que vous ne voulez pas voir entrer en conflit. Le générateur émet `UserInput` comme type séparé (il n'écrase pas `User`), vous pouvez donc garder les deux dans un seul fichier sans collision.
- Documentation du schéma pour l'équipe frontend. Les ingénieurs front ne veulent pas apprendre le SDL GraphQL. Collez le schéma ici, envoyez le TS généré : l'autre équipe voit les mêmes types que le backend, mais dans le langage qu'elle connaît.
- Construction de mocks de test. Les interfaces émises ici sont idéales pour `Factory<User>` en `vitest` / `jest` : vous mockez les réponses serveur, le compilateur vérifie que vous n'avez oublié aucun champ.
Pour les API REST, l'outil correspondant est OpenAPI vers TypeScript. Pour des échantillons JSON ponctuels sans schéma, JSON vers TypeScript est plus rapide.