GraphQL Formatter: Beautify and Minify Queries, Mutations and Schemas

A REST URL is flat — the path and query string are the whole request. A GraphQL query has no such ceiling: selection sets nest inside selection sets, fragments get spread into other fragments, and directives like @include and @skipattach conditions to individual fields. Add variable definitions at the top of the operation and it's easy to end up with a document five or six levels deep before you've queried anything unusual. None of that depth is a problem for the GraphQL engine executing it — it's a problem for the person reading it, especially once the query has been copy-pasted between a client codebase, a GraphiQL tab, and a bug report, each pass losing a little more of its original indentation.

A GraphQL formatter — sometimes searched for as a GraphQL beautifier or GraphQL prettify tool — exists for exactly that reason: it re-indents the document consistently based on its actual nesting, the same service a JSON formatter provides for deeply nested JSON. The underlying principle is identical in both cases — the formatter has to understand the document's structure, not just react to brace and bracket characters in the text.

“GraphQL” isn't one kind of document — a formatter that only handles queries is missing most of what people actually paste in. There are four related but distinct forms, all valid GraphQL syntax that a formatter needs to parse and print correctly:

• Queries — read operations, the most common case: a named operation with a selection set and, usually, variable definitions.
• Mutations — write operations. Structurally identical to a query (variables, a selection set, an operation name) but declared with the mutation keyword instead of query.
• Fragments — a named, reusable selection set declared with fragment and spread into an operation with ...FragmentName. Formatting a document that spreads three or four fragments into a query is where indentation drift shows up fastest, because each fragment was likely pasted in from a different file.
• SDL — Schema Definition Language. This is the odd one out and worth being precise about: SDL is the syntax used to describe a schema — type, input, enum, interface, and scalar declarations — not to query one. A .graphqlschema file and a query sent from a client share a grammar family but serve opposite purposes: one defines what's queryable, the other queries it. A formatter that only recognizes operations will choke the moment you paste in a schema file, so it needs to parse both grammars.

The most common input in practice isn't hand-typed — it's a query copied out of a Slack thread, a network tab, or a minified bundle, where every newline collapsed into one line somewhere along the way. Reformatting it should recover exactly the structure the query already has, nothing added or reordered:

query GetUser($id: ID!, $includeOrders: Boolean = false) { user(id: $id) { id name email orders @include(if: $includeOrders) { id total items { sku quantity } } } }

query GetUser($id: ID!, $includeOrders: Boolean = false) {
  user(id: $id) {
    id
    name
    email
    orders @include(if: $includeOrders) {
      id
      total
      items {
        sku
        quantity
      }
    }
  }
}

Notice the @include directive stays attached to the field it modifies rather than being pushed to its own line — a formatter that understands the grammar knows a directive is part of the field it decorates, not a standalone token to wrap independently.

This is the detail worth being precise about, because it's the difference between a formatter you can trust and one that quietly lies to you. A GraphQL formatter built on a real parser — the same class of tool the reference GraphQL implementations use to validate a document before execution — has to build an actual syntax tree from the input. An unclosed brace, a variable definition missing its type, a dangling comma where the grammar doesn't allow one: all of these fail to parse, and a parser-based tool reports exactly where, with a line and column, the same way a real JSON parser reports a trailing comma.

A string-based reformatter — one that just counts braces and inserts indentation based on nesting depth inferred from characters — has no such check. Feed it a query with a brace missing and it will still produce something that looks tidy: consistent indentation, aligned fields, no visible complaint. It is still invalid GraphQL. It will fail the moment a client or server actually tries to parse it, just later and with a less useful error than the formatter could have given you up front.

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name


→ Syntax Error: Expected Name, found <EOF> (line 6, column 1)

The missing closing brace for both user and the operation itself is a genuine syntax error, and a parser-backed formatter surfaces it instead of guessing at how to indent something that never had valid structure to begin with.

Format and minify a GraphQL query are the same transformation run in opposite directions — exactly the relationship between beautifying and minifying JSON. Format a query when a human is going to read it: a teammate reviewing a pull request, you debugging a resolver, or a query sitting in a .graphql file in a codebase where readability matters for the next person who touches it. Minify — strip whitespace, comments, and unnecessary line breaks — when only the bytes matter: a query embedded in a client bundle, sent over the wire, or persisted as an operation string on a server that supports persisted queries.

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
  }
}
↓
query GetUser($id: ID!) { user(id: $id) { id name } }

Neither direction changes what the query does. A client sending the minified form and a developer reading the formatted form in an IDE are looking at the same operation — the same guarantee a JSON minifier gives for data, applied here to an executable document instead.

GenKitLab's GraphQL Formatter formats or minifies a query, mutation, fragment, or SDL schema document using a real GraphQL parser, so a genuine syntax error — an unclosed brace, a malformed variable definition — is reported with the exact line and column it occurs at, rather than papered over with indentation that merely looks correct. It runs entirely client-side: nothing you paste is uploaded anywhere, which matters for a query that includes field names or fragment structure you'd rather not send to a third-party server just to reformat it.