Invoer

Uitvoer

Wat is de GraphQL Formatter?

Een GraphQL-schema dat uit een code generator, een federation composer of een copy-paste vanuit een chatvenster komt, heeft bijna nooit de witruimte die je wilt. Types lopen in elkaar over, velden delen een regel, beschrijvingen worden tegen de volgende definitie aangedrukt. De GraphQL schema definition language hoort het leesbare contract tussen je frontend en backend te zijn — maar alleen als het ook echt is opgemaakt. Plak je SDL in het linkerpaneel en het rechterpaneel geeft het netjes terug: twee spaties inspringing, één veld per regel, argumenten inline, en eventuele block-string-beschrijvingen blijven boven het type of veld dat ze documenteren.

De pretty-printer is met de hand geschreven — er wordt geen graphql npm-pakket op de pagina geladen, dus de eerste paint blijft licht. Hij tokeniseert het SDL, loopt door de accolade-structuur en geeft het opnieuw uit met consistente spacing volgens de GraphQL-spec van oktober 2021. Elke SDL-constructie die je in echte schemas tegenkomt, wordt afgehandeld: type, interface, union, enum, input, scalar, extend, schema, directive, list- en non-null-modifiers ([Foo!]!), default-waarden, directives en triple-quoted beschrijvingen. De formatter is idempotent — al netjes opgemaakte SDL komt onveranderd terug, dus je kunt hem rustig in een CI-gate of een pre-commit-hook draaien.

Alles draait in je browser. Geen upload, geen schema dat ergens wordt opgeslagen. Plakken, opmaken, kopiëren.

Hoe gebruik je de GraphQL Formatter

Drie snelle stappen. De knoppen die hieronder beschreven worden, zijn de echte knoppen op deze pagina.

Plak, upload of laad een voorbeeld

Plak een GraphQL-schema in het linker Invoer-paneel — formatten gebeurt automatisch een fractie van een seconde nadat je stopt met typen, dus je hoeft niet naar een Convert-knop te zoeken. Klik op Uploaden voor een .graphql-, .graphqls- of .gql-bestand, of op Voorbeeld om een realistisch e-commerce Order-schema te laden. Een typische rommelige plak ziet er zo uit:

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

Server-style schemas (met extend type Query) en losse type-definities werken allebei. De geaccepteerde vormen komen overeen met wat tools als Apollo Server bij het opstarten parsen.

Lees de mooie uitvoer

Het rechter Uitvoer-paneel rendert het opgemaakte SDL met twee spaties inspringing. Elk veld, enum-waarde en union-member krijgt zijn eigen regel. Argumenten blijven inline op de veldregel zodat signatures natuurlijk lezen. Beschrijvingen die als block strings ("""...""") zijn geschreven, blijven boven het type of veld dat ze beschrijven — zo raadt de Relay GraphQL-specificatie aan om een schema te documenteren. Als het SDL ongebalanceerde accolades of een andere parse-fout heeft, toont de formatter een vriendelijke inline-melding — hij gooit nooit een exception en crasht niet.

Kopieer of download

Klik op Kopiëren om het opgemaakte schema mee te nemen naar een pull request, doc of chat. Klik op Downloaden om als .graphql op te slaan. De clear-knop op het invoerpaneel zet je terug naar een lege staat. Formatten gebeurt volledig client-side — je schema verlaat de pagina nooit.

Wanneer je dit echt zou gebruiken

Leesbaarheid bij PR-reviews

Een teamlid opent een PR die vijf nieuwe types aan je schema toevoegt. De diff lijkt één gigantisch blok omdat de codegen-output de opmaak heeft weggegooid. Haal het bestand door de formatter en plak de verfraaide versie in de PR-beschrijving zodat reviewers daadwerkelijk kunnen lezen wat er wordt toegevoegd. GraphQL-schema best practices volgen is een stuk makkelijker als reviewers de structuur kunnen zien.

Schema-registry diffs

De meeste schema-registries (Apollo Studio, GraphQL Hive, Hasura) tonen diffs als regel-voor-regel tekst. Als de ene revisie geminificeerd was en de volgende netjes, lijkt elke regel veranderd en verdwijnt de echte verandering in de ruis. Verfraai beide versies voor het uploaden — zelfde formatter, zelfde uitvoer, echte diff.

Docs en onboarding

Schrijf je publieke docs voor een GraphQL-API of onboard je een nieuwe engineer? Plak het schema, kopieer de opgemaakte versie naar de wiki of README. Een schema met zichtbare beschrijvingen boven elk type is een veel vriendelijker startpunt dan de ongeformateerde brei die het codegen-tool eruit gooide.

Pre-commit en CI-gates

Omdat de formatter idempotent is, kun je hem als pre-commit-hook of CI-check draaien: format het schema, laat de build falen als het resultaat afwijkt van het gecommitte bestand. Geen whitespace-drift meer tussen contributors en geen PRs meer waarvan de helft van de diff alleen reformat-ruis is.

Veelgestelde vragen

Valideert hij mijn schema, of formatteert hij het alleen?

Alleen formatteren. De formatter controleert de balans van accolades en aanhalingstekens net genoeg om pretty-print te kunnen doen, maar hij verifieert niet dat Query bestaat, dat verwezen types gedefinieerd zijn of dat directive-argumenten matchen met hun definities. Voor volledige validatie haal je je schema door de referentie-implementatie graphql-js of door de startup-checks van je server.

Wordt mijn schema naar een server gestuurd?

Nee. Het formatten draait volledig in je browser. Niets wordt geüpload, niets wordt gelogd. Veilig om interne of nog niet uitgebrachte schemas te plakken.

Behandelt hij block-string-beschrijvingen?

Ja. Triple-quoted beschrijvingen ("""Een door een klant geplaatste bestelling.""") blijven behouden en worden uitgegeven op de regel boven het type of veld dat ze documenteren. Dat is de canonieke manier om SDL-documentatie te schrijven volgens de GraphQL-spec.

En directives en custom scalars?

Allebei behouden. @deprecated, @key en elke custom directive blijven inline op het veld. Custom scalars zoals scalar DateTime komen op hun eigen regel. De formatter probeert de semantiek van directives niet te interpreteren — dat is aan je server.

Wordt al opgemaakte SDL opnieuw geformatteerd?

Het is idempotent — al netjes SDL nogmaals opmaken levert dezelfde uitvoer op. Je kunt de formatter dus in een CI-check of een plak-en-vergelijk-workflow draaien zonder je zorgen te maken over whitespace-drift.

Hoe groot mag het schema zijn dat ik plak?

Wat je browser comfortabel kan renderen. Schemas van een paar honderd types zijn geen probleem. Boven de 5 MB wordt de Ace-editor zelf langzamer — daar zit het knelpunt, niet bij de parser.

Andere GraphQL-tools

Formatten is maar één onderdeel van werken met GraphQL. Deze tools doen de rest: