Entrée

Sortie

C’est quoi le formateur GraphQL ?

Un schéma GraphQL sorti d’un générateur de code, d’un compositeur de fédération ou d’un copier-coller depuis un chat n’a presque jamais l’espacement qu’on voudrait. Les types se touchent, les champs partagent la même ligne, les descriptions se collent à la définition suivante. Le langage de définition de schéma GraphQL est censé être le contrat lisible entre votre frontend et votre backend — mais seulement s’il est correctement formaté. Collez votre SDL dans le panneau de gauche et celui de droite vous le renvoie embelli : indentation de deux espaces, un champ par ligne, arguments en ligne, et les descriptions en chaîne de bloc placées au-dessus du type ou du champ qu’elles documentent.

Le pretty-printer est fait maison — aucun paquet npm graphql n’est chargé dans la page, donc le premier rendu reste léger. Il tokenise le SDL, parcourt la structure d’accolades et le ré-émet avec un espacement cohérent conforme à la spécification GraphQL d’octobre 2021. Toutes les constructions SDL qu’on croise dans la vraie vie sont prises en charge : type, interface, union, enum, input, scalar, extend, schema, directive, modificateurs de liste et non-null ([Foo!]!), valeurs par défaut, directives, et descriptions entre triples guillemets. Le formateur est idempotent — un SDL déjà joli ressort identique, donc vous pouvez le brancher dans une étape CI ou un hook pre-commit sans souci.

Tout tourne dans votre navigateur. Pas d’upload, aucun schéma stocké quelque part. Collez, embellissez, copiez.

Comment utiliser le formateur GraphQL

Trois étapes rapides. Les boutons décrits ci-dessous sont les vrais boutons de cette page.

Coller, importer ou charger un exemple

Collez un schéma GraphQL dans le panneau Entrée à gauche — le formatage se fait automatiquement une fraction de seconde après que vous arrêtez de taper, pas besoin de chercher un bouton Convertir. Cliquez sur Importer pour un fichier .graphql, .graphqls ou .gql, ou sur Exemple pour charger un schéma e-commerce Order réaliste. Un collage typique tout cassé ressemble à ça :

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

Les schémas style serveur (avec extend type Query) comme les définitions de types autonomes fonctionnent. Les formes acceptées correspondent à ce que des outils comme Apollo Server parsent au démarrage.

Lisez la sortie embellie

Le panneau Sortie à droite affiche le SDL embelli avec une indentation de deux espaces. Chaque champ, valeur d’enum et membre d’union a sa propre ligne. Les arguments restent en ligne sur la ligne du champ pour que les signatures se lisent naturellement. Les descriptions écrites en chaînes de bloc ("""...""") sont placées au-dessus du type ou champ qu’elles décrivent, comme le recommande la spécification GraphQL de Relay pour documenter un schéma. Si le SDL a des accolades non équilibrées ou toute autre erreur de parsing, le formateur affiche un message inline lisible — il ne lève jamais d’exception et ne plante pas.

Copier ou télécharger

Cliquez sur Copier pour récupérer le schéma formaté pour une pull request, une doc ou un chat. Cliquez sur Télécharger pour l’enregistrer en .graphql. Le bouton effacer du panneau d’entrée vous remet à zéro. Le formatage se fait entièrement côté client — votre schéma ne quitte jamais la page.

Les cas où c’est vraiment utile

Lisibilité en revue de PR

Un collègue ouvre une PR qui ajoute cinq nouveaux types à votre schéma. Le diff ressemble à un seul gros bloc parce que la sortie du codegen a perdu son formatage. Passez le fichier dans le formateur, puis collez la version embellie dans la description de la PR pour que les relecteurs puissent vraiment lire ce qui est ajouté. Suivre les bonnes pratiques pour les schémas GraphQL est bien plus facile quand les relecteurs voient la structure.

Diffs de registres de schéma

La plupart des registres de schémas (Apollo Studio, GraphQL Hive, Hasura) affichent les diffs en texte ligne par ligne. Si une révision était minifiée et la suivante était jolie, chaque ligne apparaît comme modifiée et le vrai changement disparaît dans le bruit. Embellissez les deux versions avant de les uploader — même formateur, même sortie, vrai diff.

Doc et onboarding

Vous écrivez la doc publique d’une API GraphQL ou vous accueillez un nouvel ingénieur ? Collez le schéma, copiez la version formatée dans le wiki ou le README. Un schéma avec ses descriptions visibles au-dessus de chaque type est un point de départ bien plus accueillant que le pavé non formaté que crache l’outil de codegen.

Hooks pre-commit et étapes de CI

Comme le formateur est idempotent, vous pouvez le lancer en hook pre-commit ou en check CI : formatez le schéma, faites échouer le build si le résultat diffère du fichier commité. Plus de dérive d’espaces entre contributeurs, plus de PR où la moitié du diff est du bruit de reformatage.

Questions fréquentes

Est-ce qu’il valide mon schéma ou il le formate juste ?

Il formate, c’est tout. Le formateur vérifie l’équilibre des accolades et des guillemets juste assez pour pretty-print, mais il ne vérifie pas que Query existe, que les types référencés sont définis, ou que les arguments de directive correspondent à leurs définitions. Pour une validation complète, passez votre schéma par l’implémentation de référence graphql-js ou par les checks de démarrage de votre serveur.

Mon schéma est-il envoyé à un serveur ?

Non. Le formatage tourne entièrement dans votre navigateur. Rien n’est uploadé, rien n’est loggé. Vous pouvez coller des schémas internes ou non publiés sans risque.

Est-ce qu’il gère les descriptions en chaînes de bloc ?

Oui. Les descriptions entre triples guillemets ("""Une commande passée par un client.""") sont préservées et émises sur la ligne au-dessus du type ou champ qu’elles documentent. C’est la façon canonique d’écrire la doc SDL selon la spec GraphQL.

Et les directives et scalars personnalisés ?

Les deux sont conservés. @deprecated, @key et toute directive personnalisée restent en ligne sur le champ. Les scalars personnalisés comme scalar DateTime sont émis sur leur propre ligne. Le formateur ne tente pas d’interpréter la sémantique des directives — c’est le boulot de votre serveur.

Un SDL déjà formaté va-t-il être reformaté ?

Il est idempotent — embellir un SDL déjà embelli produit la même sortie. Vous pouvez donc lancer le formateur dans un check CI ou un workflow coller-puis-comparer sans craindre la dérive d’espaces.

Quelle taille de schéma puis-je coller ?

Tout ce que votre navigateur affiche confortablement. Les schémas de quelques centaines de types ne posent aucun problème. Au-delà de 5 Mo, c’est l’éditeur Ace lui-même qui commence à ralentir — c’est le goulot d’étranglement, pas le parser.

Autres outils GraphQL

Le formatage n’est qu’une partie du travail avec GraphQL. Ces outils s’occupent du reste :

Formateur GraphQL