Entrada

Saída

O que é o Formatador GraphQL?

Um schema GraphQL que saiu de um gerador de código, de um composer de federação ou de um copia-e-cola de uma janela de chat quase nunca tem o espaçamento que você quer. Tipos colados, campos dividindo linha, descrições espremidas contra a próxima definição. A linguagem de definição de schema do GraphQL deveria ser o contrato legível entre seu frontend e seu backend — mas só se estiver realmente formatada. Cole seu SDL no painel da esquerda e o painel da direita devolve ele bonito: indentação de dois espaços, um campo por linha, argumentos inline, e qualquer descrição em block string mantida acima do tipo ou campo que documenta.

O pretty-printer foi feito à mão — nenhum pacote npm graphql é carregado na página, então o primeiro paint continua leve. Ele tokeniza o SDL, percorre a estrutura de chaves e re-emite com espaçamento consistente conforme a spec do GraphQL de outubro de 2021. Toda construção SDL que aparece em schemas reais é tratada: type, interface, union, enum, input, scalar, extend, schema, directive, modificadores de lista e non-null ([Foo!]!), valores padrão, diretivas e descrições com aspas triplas. O formatador é idempotente — SDL já bonito volta igual, então você pode rodar dentro de um gate de CI ou de um hook pre-commit sem susto.

Tudo roda no seu navegador. Sem upload, sem schema guardado em lugar nenhum. Cole, embeleze, copie.

Como usar o Formatador GraphQL

Três passos rápidos. Os botões descritos abaixo são os botões reais nesta página.

Cole, envie ou carregue um exemplo

Cole um schema GraphQL no painel Entrada à esquerda — a formatação acontece automaticamente uma fração de segundo depois que você para de digitar, então não tem botão Convert para procurar. Clique em Enviar para um arquivo .graphql, .graphqls ou .gql, ou em Exemplo para carregar um schema realista de Order de e-commerce. Uma colagem típica e bagunçada parece com isso:

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

Schemas estilo servidor (com extend type Query) e definições de tipo soltas funcionam. As formas aceitas batem com o que ferramentas como Apollo Server parseiam no startup.

Leia a saída embelezada

O painel Saída à direita renderiza o SDL bonito com indentação de dois espaços. Cada campo, valor de enum e membro de union ganha sua própria linha. Argumentos ficam inline na linha do campo para as assinaturas lerem naturalmente. Descrições escritas como block strings ("""...""") ficam acima do tipo ou campo que descrevem, que é como a spec GraphQL do Relay recomenda documentar um schema. Se o SDL tiver chaves desbalanceadas ou qualquer outro erro de parse, o formatador mostra uma mensagem amigável inline — nunca lança exceção nem trava.

Copie ou baixe

Clique em Copiar para levar o schema formatado para um pull request, doc ou chat. Clique em Baixar para salvar como .graphql. O botão de limpar no painel de entrada te devolve para o estado em branco. A formatação acontece inteiramente no cliente — seu schema nunca sai da página.

Quando você realmente usaria isto

Legibilidade em revisão de PR

Um colega abre um PR que adiciona cinco tipos novos ao seu schema. O diff parece um bloco gigante porque a saída do codegen tirou a formatação. Passa o arquivo pelo formatador e cola a versão bonita na descrição do PR para os revisores realmente conseguirem ler o que está sendo adicionado. Seguir as melhores práticas de schemas GraphQL fica muito mais fácil quando os revisores enxergam a estrutura.

Diffs em registries de schema

A maioria das registries de schema (Apollo Studio, GraphQL Hive, Hasura) mostra diffs como texto linha por linha. Se uma revisão estava minificada e a próxima estava bonita, toda linha aparece como mudada e a mudança real some no ruído. Embeleze as duas versões antes de subir — mesmo formatador, mesma saída, diff de verdade.

Docs e onboarding

Escrevendo docs públicas de uma API GraphQL ou treinando uma engenheira nova? Cola o schema, copia a versão formatada para o wiki ou README. Um schema com descrições visíveis acima de cada tipo é um ponto de partida muito mais amigável do que o monte sem formatação que a ferramenta de codegen cuspiu.

Hooks pre-commit e gates de CI

Como o formatador é idempotente, dá para rodar como hook pre-commit ou check de CI: formate o schema, falhe o build se o resultado for diferente do arquivo commitado. Acabou a deriva de espaço em branco entre contribuidores e PRs onde metade do diff é só ruído de reformatação.

Perguntas frequentes

Ele valida meu schema ou só formata?

Só formata. O formatador checa o balanço de chaves e aspas o suficiente para fazer pretty-print, mas não verifica se Query existe, se os tipos referenciados estão definidos ou se os argumentos das diretivas batem com a definição. Para validação completa, passe seu schema pela implementação de referência graphql-js ou pelos checks de startup do seu servidor.

Meu schema é enviado para algum servidor?

Não. A formatação roda inteiramente no seu navegador. Nada é enviado, nada é logado. Pode colar schemas internos ou ainda não publicados sem medo.

Ele lida com descrições em block string?

Sim. Descrições com aspas triplas ("""Um pedido feito por um cliente.""") são preservadas e emitidas na linha acima do tipo ou campo que documentam. É a forma canônica de escrever documentação SDL pela spec do GraphQL.

E diretivas e scalars customizados?

Os dois são mantidos. @deprecated, @key e qualquer diretiva customizada continuam inline no campo. Scalars customizados como scalar DateTime saem em sua própria linha. O formatador não tenta interpretar a semântica das diretivas — isso é trabalho do seu servidor.

SDL já formatado é re-formatado?

É idempotente — embelezar SDL já embelezado produz a mesma saída. Então dá para rodar o formatador num check de CI ou num fluxo de colar-e-comparar sem se preocupar com deriva de espaço em branco.

Quão grande pode ser o schema que eu colo?

O que seu navegador conseguir renderizar confortavelmente. Schemas de algumas centenas de tipos não são problema. Acima de 5 MB o próprio editor Ace começa a lentificar — esse é o gargalo, não o parser.

Outras ferramentas GraphQL

Formatar é só uma parte de trabalhar com GraphQL. Estas ferramentas cuidam do resto: