GraphQL Formatter

A GraphQL formatter for operations and schemas

GraphQL documents often arrive as one long line: copied from browser dev tools, logged by a server, or embedded in a JavaScript string. This GraphQL formatter parses the document with Prettier's GraphQL parser (built on the reference graphql-js grammar) and prints it with one field per line and nested selection sets indented. It works for both executable documents (queries, mutations, subscriptions, fragments) and schema definition language (SDL).

Example

mutation AddReview($ep:Episode!,$review:ReviewInput!){createReview(episode:$ep,review:$review){stars commentary ...ReviewMeta}}
fragment ReviewMeta on Review{id createdAt author{name}}
type Review @key(fields:"id"){id:ID! stars:Int! commentary:String}

mutation AddReview($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    stars
    commentary
    ...ReviewMeta
  }
}
fragment ReviewMeta on Review {
  id
  createdAt
  author {
    name
  }
}
type Review @key(fields: "id") {
  id: ID!
  stars: Int!
  commentary: String
}

Commas between fields are dropped (in GraphQL they are optional "insignificant" commas), while commas between arguments and variable definitions are added for readability. The directive @key and its arguments keep their position.

Supported GraphQL syntax

Options

Indent is 2 spaces by default, which is what the GraphQL specification examples and most tooling use. Line width matters for long argument lists: when a field's arguments do not fit, each argument goes on its own line. A very long @key(fields: "...") string is never split.

GraphQL naming conventions

A formatter fixes layout; naming is up to you, but a few conventions are nearly universal and match the examples in the GraphQL specification:

• Types, interfaces, unions and enums in PascalCase; fields and arguments in camelCase; enum values in SCREAMING_SNAKE_CASE.
• Input types end in Input (ReviewInput), and mutations are verbs (createReview, cancelOrder).
• Give every operation a name, such as query GetUser. Anonymous operations work, but named ones show up in server logs, tracing and client caches, which makes debugging much easier.

Common GraphQL syntax errors

• "Expected Name, found }" – an empty selection set such as user { }. Every selection set needs at least one field.
• "Expected :, found ..." – a variable definition without a type, like ($id); write ($id: ID!).
• Unterminated string – GraphQL strings use double quotes only; single quotes are not valid.
• Unexpected character – a stray symbol such as a trailing semicolon; GraphQL documents do not use semicolons.

The formatter checks syntax, not validity against a schema: a misspelled field name or a wrong argument type still formats, because the parser never sees your schema. Use your GraphQL server or an IDE plugin to validate against the schema.

GraphQL in JavaScript files

Queries embedded with gql`...` tags live inside JavaScript. Prettier formats those tagged templates when you format the JavaScript file itself, so run the whole file through JavaScript Pretty Print to keep both consistent. Formatting two versions of a query the same way also makes the Diff Checker show only the fields that really changed. To inspect the JSON a query returns, use the JSON Formatter. Everything on this page runs in your browser.