GraphQL Formatter

A query is easiest to review when its selection sets are visible

GraphQL documents can become deeply nested even when the operation itself is straightforward. Fields, fragments, directives, variables, arguments, aliases, and inline fragments compete for attention. A GraphQL Formatter should make selection-set depth obvious so a reviewer can see what the client requests and where an expensive nested relationship begins.

This tool supplies a simple side-by-side line indenter with two- and four-space options. It trims non-empty lines, drops empty lines, decreases indentation for a line beginning with }, and increases indentation when a line ends with {. Copy sends the current formatted result to the clipboard. It does not parse GraphQL tokens, split a compact query at braces, load a schema, or validate an operation. The most productive use therefore starts with an operation that already has structural line breaks.

Prepare input for useful output

This single-line query remains a single line:

query Product($id: ID!) { product(id: $id) { id name variants { id price } } }

The component works on physical lines, so first place selection-set braces and fields on sensible lines:

query Product($id: ID!) {
product(id: $id) {
id
name
variants {
id
price
}
}
}

With two spaces selected, the output becomes:

query Product($id: ID!) {
  product(id: $id) {
    id
    name
    variants {
      id
      price
    }
  }
}

That result is easier to inspect, but the tool did not determine whether Product exists, $id has the right type, variants accepts arguments, or price is selectable. Layout and validation remain separate tasks.

Two spaces or four?

Two-space indentation is common in GraphQL tooling and keeps deep selection sets relatively narrow. Four spaces can make level changes more prominent in short operations, particularly in documentation. Choose the convention used by checked-in .graphql files, generated artifacts, or the formatter configured by the client project.

Indent width is the only formatting preference exposed. There are no controls for commas, argument wrapping, directive placement, fragment layout, maximum line length, or operation sorting. The formatter also removes blank lines, so deliberate spacing between operations or fragment definitions must be restored manually.

Because formatting updates immediately, switching widths is useful for comparing readability before selecting text. The Raw Code pane remains editable, while Formatted Code is read-only. An empty source yields empty output. No file is uploaded or schema endpoint contacted by the component.

An operation-review routine

Begin with one named operation and the fragments it directly uses. Add structural line breaks in an editor if the query is compressed. Paste the text, choose indentation, and compare every opening and closing selection-set brace. Check that aliases, arguments, variable definitions, and directives remain attached to the intended field.

Copy the result into a GraphQL-aware editor or client. Parse it with the same GraphQL implementation used by the application. Validate against the correct schema version, because a syntactically valid document can still reference missing fields, violate argument requirements, or select an object without subfields. Execute it in a non-production environment with representative authorization and variables.

For persisted operations, regenerate hashes after formatting if the system hashes exact source text. Whitespace is generally insignificant to GraphQL execution, but persisted-query registries, snapshots, signatures, caches, and golden files may treat the document as bytes. Coordinate changes rather than assuming cosmetic edits have no deployment effect.

For client applications, run document code generation after formatting. Typed document nodes, generated hooks, operation manifests, and fragment masking outputs can reveal mismatches that a visual review cannot.

GraphQL syntax this tool does not interpret

Selection braces are only part of the language. Input objects and variable values also use braces, while lists use square brackets. The generic formatter can increase after a line ending in [ and decrease for a line beginning with ], but it has no understanding of whether those tokens appear inside a string, default value, argument, or type-system definition.

GraphQL supports block strings delimited by triple quotes. Their indentation participates in value normalization, and trimming each physical line can alter presentation or content. Descriptions in schema definition language often use block strings, making SDL particularly sensitive to line-based formatting.

Comments begin with # and continue to the line end. They remain as non-empty trimmed lines but are indented solely according to surrounding tracked braces. Blank comment separators disappear when represented as empty lines. Tool directives embedded in comments are not recognized.

Fragment spreads such as ...ProductFields, inline fragments with ... on Product, and directives like @include(if: $showPrice) are retained as text. There is no check that a spread is reachable, fragment names are unique, variables are used, or directive locations are legal.

The same page may accept schema definition language text, but it does not distinguish type, input, interface, enum, union, scalar, directive, and schema definitions. Use a GraphQL parser and schema linter for SDL formatting and validation.

Formatting versus query quality

A neatly printed query can still be expensive. Deep nesting, broad connections, repeated aliases, large page sizes, and resolver-level N+1 behavior require schema-specific analysis. Formatting simply makes those patterns easier to notice. It does not calculate complexity, enforce depth limits, estimate response size, or inspect resolver performance.

Good operation review asks whether every field is rendered or used, whether fragments express stable component boundaries, whether pagination is bounded, and whether sensitive fields are requested unnecessarily. Server controls should still impose authorization, validation rules, cost limits, and timeouts. A client-side beautifier is not a security control.

Named operations are preferable to anonymous operations in production because logs and traces become easier to correlate. Meaningful aliases help only when they clarify response roles. Fragments reduce duplication but can conceal the final expanded field set, so inspect generated or expanded operations when investigating cost.

When the output looks wrong

Nothing changed for a compact query. Add line breaks first or use a parser-based GraphQL pretty printer that can tokenize one-line source.

Closing braces did not align. A closing brace must begin its trimmed line to reduce indentation before emission. Move it to its own line and retry.

Blank lines between operations vanished. Empty lines are skipped. Reinsert separation after copying or use canonical project formatting.

A block string changed. Restore it from untouched source. This tool trims lines without recognizing string boundaries.

The query is formatted but the server rejects it. Formatting supplies no syntax or schema validation. Check parse errors, schema version, variables, operation name, authentication, and validation diagnostics in a GraphQL client.

GraphQL Formatter FAQ

Can it beautify a one-line GraphQL query?

It will trim and re-emit that line, but it will not split fields or braces onto new lines. Add line boundaries first or use an AST-based printer.

Does it validate against my schema?

No. The component does not request or accept a schema. Validate with your server, IDE language service, GraphQL CLI, or code-generation pipeline.

Can I format mutations and subscriptions?

Yes, when their braces are already distributed across lines. Operation type does not change the indentation algorithm.

Are variables or fragments reordered?

No. Text order remains the same apart from whitespace trimming and removal of blank lines.

Is four-space indentation more correct?

GraphQL syntax does not mandate either width. Two spaces is widespread, but repository consistency is the practical standard.

Will whitespace changes affect persisted queries?

They can. Systems that hash exact operation text produce a different identifier when whitespace changes. Regenerate and deploy manifests according to the application’s persisted-operation workflow.

What should happen before committing output?

Run the project’s GraphQL formatter, parse the document, validate it against the intended schema, regenerate typed artifacts and manifests, execute tests, and inspect the diff for block strings or removed spacing.

Keep operation text useful in reviews

Formatting works best when it supports a specific review question. Put pagination arguments beside the connection field, keep conditional directives visible, and avoid unrelated field reordering in the same change. Reviewers can then distinguish a new data requirement from a purely presentational edit. If an operation is shared across clients, confirm that changing its exact text does not invalidate allowlists, telemetry grouping, recorded fixtures, or gateway registrations. A small, focused diff provides more confidence than reprinting every query in a repository at once.