GraphQL Compose Codegen | Wilkes & Liberty

GraphQL Compose Codegen está dirigido a equipos de Drupal y Next.js que quieren que el esquema Drupal en vivo, y no un archivo TypeScript mantenido a mano, defina el contrato entre el contenido del backend y el código del frontend. El módulo Drupal con licencia GPL es mantenido por Jeremy Michael Cerda y Wilkes & Liberty. Se ejecuta dentro de Drupal mediante Drush, inspecciona el esquema producido por GraphQL Compose y genera tipos TypeScript, fragmentos GraphQL, consultas y andamiajes de componentes React revisables.

Por qué existe

Una compilación de Drupal desacoplado puede compilar sin errores mientras su contrato en tiempo de ejecución ya se ha desviado. Un campo se renombra en Drupal, un bundle se elimina o un Paragraph cambia de forma; los tipos escritos a mano del frontend siguen describiendo el esquema de ayer. La falla llega después, como una consulta inválida, una página en blanco o una capa defensiva de campos opcionales que oculta una integración rota.

GraphQL Compose Codegen convierte el esquema Drupal en la fuente de verdad. Los archivos generados se convierten en artefactos de compilación que se pueden inspeccionar, confirmar en el repositorio y verificar en CI. Cuando el modelo de contenido cambia, la diferencia aparece como revisión de código y no como una sorpresa en producción.

Quién debería usarlo y cuándo

Constructores de sitios Drupal que son dueños de los tipos de contenido y modelos de Paragraph y necesitan que los equipos de frontend vean los cambios de esquema con prontitud.
Equipos de Next.js y TypeScript que construyen contra GraphQL Compose y quieren un punto de partida tipado para consultas y componentes.
Equipos de plataforma que mantienen varios entornos donde el desvío de esquema debe hacer fallar una puerta de despliegue en lugar de una página.
Agencias y equipos regulados que necesitan una transferencia inspeccionable y repetible entre la configuración de contenido y el código de la aplicación.

Úselo cuando Drupal sea dueño del modelo de contenido y un frontend TypeScript consuma GraphQL Compose. Es especialmente útil al iniciar un proyecto, después de cambios en el modelo y en CI antes de que un cambio de configuración de Drupal y una versión del frontend avancen de forma independiente.

Dónde se ejecuta

El módulo se ejecuta en la aplicación Drupal, donde puede leer directamente las definiciones de entidades de Drupal y el esquema de GraphQL Compose. Drush es una dependencia obligatoria porque la generación es una tarea de operador y de CI, no un endpoint HTTP. La salida se escribe en un directorio de frontend elegido o se imprime para su revisión. El código generado pasa entonces a pertenecer al repositorio del frontend y sigue el proceso normal de lint, pruebas y revisión de ese repositorio.

Qué genera

Tipos TypeScript para los bundles y campos de Drupal expuestos por GraphQL.
Fragmentos GraphQL que coinciden con el esquema detectado.
Andamiajes de consultas y esbozos de componentes React para nuevos bundles de contenido.
Uniones conscientes de Paragraphs y puntos de partida de componentes para modelos de página componibles.
Un manifiesto que registra lo generado y respalda las verificaciones de desvío.
Avisos cuando cambian los bundles o campos expuestos, para que la evolución del modelo sea visible para los operadores.

Flujo de trabajo del operador

Configure qué esquema de GraphQL Compose y qué bundles deben participar.
Inspeccione el modelo detectado antes de escribir archivos.
Ejecute la generación en modo de vista previa o imprima la salida en la salida estándar para su revisión.
Escriba los andamiajes en el directorio de archivos generados del frontend.
Integre los fragmentos y tipos generados en las consultas y componentes específicos de la aplicación.
Ejecute el comando de desvío en CI; una salida distinta de cero indica a la canalización que los artefactos confirmados ya no coinciden con Drupal.

composer require drupal/graphql_compose_codegen
drush en graphql_compose_codegen

# Inspect the live schema and planned artifacts.
drush gqcc:inspect

# Preview without writing.
drush gqcc:generate --output-dir=../ui --dry-run

# Generate into a frontend directory.
drush gqcc:generate --output-dir=../ui

# Fail CI when generated artifacts have drifted.
drush gqcc:validate --output-dir=../ui

Lo que los equipos siguen teniendo a su cargo

El generador crea un andamiaje tipado, no una interfaz de usuario terminada. No puede decidir la arquitectura de la información, el comportamiento de los componentes, la accesibilidad, el almacenamiento en caché, la autorización de vista previa, los estados de error ni qué campos debería consultar realmente una página. El código generado debe revisarse como cualquier otra salida de dependencia. Los sitios con extensiones de esquema GraphQL personalizadas pueden necesitar un mapeador de tipos de campo adicional; el módulo expone un punto de extensión para ese trabajo.

Tampoco reemplaza la validación de documentos GraphQL en tiempo de compilación del frontend. La canalización más sólida usa ambas: generar y verificar el desvío desde Drupal, y luego validar las operaciones reales de la aplicación contra el esquema.

Requisitos y compatibilidad

PHP 8.1 o superior.
Drupal 10.6+ u 11.3+.
GraphQL Compose 2.1 o 3.x.
Drush 12 o 13.
Un consumidor TypeScript/GraphQL; el andamiaje incluido apunta a las estructuras habituales de proyectos Next.js y React.

Proyecto, código fuente, incidencias y contribución

Las contribuciones son bienvenidas bajo GPL-2.0-or-later. La versión de código fuente verificada para esta página es la 1.1.0.