Entrada

Salida

¿Qué es el formateador de GraphQL?

Un esquema GraphQL que sale de un generador de código, de un compositor de federación o de un copiar y pegar desde una ventana de chat casi nunca tiene los espacios en blanco que quieres. Los tipos se pegan, los campos comparten línea, las descripciones quedan aplastadas contra la siguiente definición. El lenguaje de definición de esquemas de GraphQL debería ser el contrato legible entre tu frontend y tu backend, pero solo si está bien formateado. Pega tu SDL en el panel izquierdo y el panel derecho te lo devuelve embellecido: sangría de dos espacios, un campo por línea, argumentos en línea y cualquier descripción en cadena de bloque mantenida encima del tipo o campo que documenta.

El pretty-printer está hecho a mano: no se carga el paquete npm graphql en la página, así que el primer pintado se mantiene ligero. Tokeniza el SDL, recorre la estructura de llaves y la vuelve a emitir con un espaciado consistente conforme a la especificación GraphQL de octubre de 2021. Se manejan todas las construcciones SDL que aparecen en esquemas reales: type, interface, union, enum, input, scalar, extend, schema, directive, modificadores de lista y no-nulo ([Foo!]!), valores por defecto, directivas y descripciones entre triples comillas. El formateador es idempotente: el SDL ya bonito sale igual, así que puedes ejecutarlo dentro de una verificación de CI o un hook pre-commit sin sorpresas.

Todo se ejecuta en tu navegador. Sin subida, sin esquema almacenado en ningún sitio. Pega, embellece, copia.

Cómo usar el formateador de GraphQL

Tres pasos rápidos. Los botones que se describen abajo son los botones reales de esta página.

Pega, sube o carga un ejemplo

Pega un esquema GraphQL en el panel izquierdo de Entrada: el formateo ocurre automáticamente una fracción de segundo después de que dejas de escribir, así que no hay que buscar un botón Convertir. Pulsa Subir para cargar un archivo .graphql, .graphqls o .gql, o pulsa Ejemplo para cargar un esquema realista de Order de e-commerce. Un pegado típico desordenado se ve así:

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

Funcionan tanto los esquemas estilo servidor (con extend type Query) como las definiciones de tipos sueltas. Las formas aceptadas coinciden con lo que herramientas como Apollo Server parsean al arrancar.

Lee la salida embellecida

El panel derecho de Salida muestra el SDL embellecido con sangría de dos espacios. Cada campo, valor de enum y miembro de unión obtiene su propia línea. Los argumentos se mantienen en línea con el campo para que las firmas se lean naturalmente. Las descripciones escritas como cadenas de bloque ("""...""") se mantienen encima del tipo o campo que describen, que es como recomienda documentar un esquema la especificación GraphQL de Relay. Si el SDL tiene llaves desbalanceadas o cualquier otro error de parseo, el formateador muestra un mensaje amistoso en línea: nunca lanza una excepción ni se cuelga.

Copia o descarga

Pulsa Copiar para llevarte el esquema formateado a un pull request, doc o chat. Pulsa Descargar para guardarlo como .graphql. El botón de limpiar del panel de entrada te devuelve a un estado en blanco. El formateo ocurre por completo en el cliente: tu esquema nunca sale de la página.

Cuándo lo usarías de verdad

Legibilidad en revisiones de PR

Un compañero abre un PR que añade cinco tipos nuevos a tu esquema. El diff parece un solo bloque enorme porque la salida del codegen perdió el formato. Pasa el archivo por el formateador y pega la versión embellecida en la descripción del PR para que los revisores realmente puedan leer lo que se está añadiendo. Seguir las mejores prácticas para esquemas GraphQL es mucho más fácil cuando los revisores ven la estructura.

Diffs en registros de esquemas

La mayoría de los registros de esquemas (Apollo Studio, GraphQL Hive, Hasura) muestran diffs como texto línea por línea. Si una revisión iba minificada y la siguiente venía bonita, todas las líneas aparecen como cambiadas y el cambio real desaparece entre el ruido. Embellece ambas versiones antes de subirlas: mismo formateador, misma salida, diff real.

Documentación y onboarding

¿Escribes documentación pública de una API GraphQL o estás incorporando a un nuevo ingeniero? Pega el esquema, copia la versión formateada en la wiki o el README. Un esquema con descripciones visibles encima de cada tipo es un punto de partida mucho más amigable que el bloque sin formato que escupió la herramienta de codegen.

Hooks pre-commit y verificaciones de CI

Como el formateador es idempotente, puedes ejecutarlo como hook pre-commit o como check de CI: formatea el esquema y haz fallar el build si el resultado difiere del archivo commiteado. Se acaba la deriva de espacios en blanco entre colaboradores y los PRs donde la mitad del diff es ruido de reformato.

Preguntas frecuentes

¿Valida mi esquema o solo lo formatea?

Solo formatea. El formateador comprueba el balance de llaves y comillas lo justo para imprimir bonito, pero no verifica que Query exista, que los tipos referenciados estén definidos o que los argumentos de las directivas coincidan con sus definiciones. Para una validación completa, pasa tu esquema por la implementación de referencia graphql-js o por las comprobaciones de arranque de tu servidor.

¿Mi esquema se envía a un servidor?

No. El formateo se ejecuta por completo en tu navegador. No se sube nada, no se registra nada. Es seguro pegar esquemas internos o aún no publicados.

¿Maneja descripciones en cadenas de bloque?

Sí. Las descripciones entre triples comillas ("""Un pedido realizado por un cliente.""") se preservan y se emiten en la línea encima del tipo o campo que documentan. Es la forma canónica de escribir documentación SDL según la especificación GraphQL.

¿Y las directivas y los escalares personalizados?

Ambos se mantienen. @deprecated, @key y cualquier directiva personalizada se quedan en línea con el campo. Los escalares personalizados como scalar DateTime se emiten en su propia línea. El formateador no intenta interpretar la semántica de las directivas: eso es cosa de tu servidor.

¿Se reformateará un SDL que ya está formateado?

Es idempotente: embellecer un SDL ya embellecido produce la misma salida. Por eso puedes ejecutar el formateador en un check de CI o en un flujo de pegar-y-comparar sin preocuparte por la deriva de espacios en blanco.

¿Qué tan grande puede ser el esquema que pegue?

Lo que tu navegador renderice cómodamente. Esquemas de unos cientos de tipos no son problema. Pasados los 5 MB el propio editor Ace empieza a ralentizarse: ese es el cuello de botella, no el parser.

Otras herramientas de GraphQL

Formatear es solo una parte del trabajo con GraphQL. Estas herramientas se encargan del resto:

Formateador de GraphQL