GraphQL Compose Codegen | Open Source

GraphQL Compose Codegen is for Drupal and Next.js teams that want the live Drupal schema—not a hand-maintained TypeScript file—to define the contract between backend content and frontend code. The GPL-licensed Drupal module is maintained by Jeremy Michael Cerda and Wilkes & Liberty. It runs inside Drupal through Drush, inspects the schema produced by GraphQL Compose, and generates reviewable TypeScript types, GraphQL fragments, queries, and React component scaffolds.

Why it exists

A headless Drupal build can compile cleanly while its runtime contract has already drifted. A field is renamed in Drupal, a bundle is removed, or a Paragraph changes shape; the frontend's handwritten types still describe yesterday's schema. The failure arrives later as an invalid query, a blank page, or a defensive layer of optional fields that hides a broken integration.

GraphQL Compose Codegen makes the Drupal schema the source of truth. Generated files become build artifacts that can be inspected, committed, and checked in CI. When the content model changes, the difference appears as code review rather than a production surprise.

Who should use it, and when

Drupal site builders who own content types and Paragraph models and need frontend teams to see schema changes promptly.
Next.js and TypeScript teams building against GraphQL Compose who want a typed starting point for queries and components.
Platform teams maintaining several environments where schema drift must fail a deployment gate rather than fail a page.
Agencies and regulated teams that need an inspectable, repeatable handoff between content configuration and application code.

Use it when Drupal owns the content model and a TypeScript frontend consumes GraphQL Compose. It is especially useful at project bootstrap, after model changes, and in CI before a Drupal configuration change and frontend release move independently.

Where it runs

The module runs in the Drupal application, where it can read Drupal entity definitions and the GraphQL Compose schema directly. Drush is a hard dependency because generation is an operator and CI task—not an HTTP endpoint. Output is written to a chosen frontend directory or printed for review. The generated code then belongs to the frontend repository and follows that repository's normal lint, test, and review process.

What it generates

TypeScript types for GraphQL-exposed Drupal bundles and fields.
GraphQL fragments that match the discovered schema.
Query scaffolds and React component stubs for new content bundles.
Paragraph-aware unions and component starting points for composable page models.
A manifest that records what was generated and supports drift checks.
Notices when exposed bundles or fields change, so model evolution is visible to operators.

Operator workflow

Configure which GraphQL Compose schema and bundles should participate.
Inspect the detected model before writing files.
Run generation in preview mode or print output to standard output for review.
Write scaffolds into the frontend's generated directory.
Integrate generated fragments and types into application-specific queries and components.
Run the drift command in CI; a nonzero exit tells the pipeline that checked-in artifacts no longer match 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

What teams still own

The generator creates a typed scaffold, not a finished user interface. It cannot decide information architecture, component behavior, accessibility, caching, preview authorization, error states, or which fields a page should actually query. Generated code should be reviewed like any other dependency output. Sites with custom GraphQL schema extensions may need an additional field-type mapper; the module exposes an extension point for that work.

It also does not replace GraphQL document validation at frontend build time. The strongest pipeline uses both: generate and drift-check from Drupal, then validate the application's actual operations against the schema.

Requirements and compatibility

PHP 8.1 or newer.
Drupal 10.6+ or 11.3+.
GraphQL Compose 2.1 or 3.x.
Drush 12 or 13.
A TypeScript/GraphQL consumer; the shipped scaffold targets common Next.js and React project shapes.

Project, source, issues, and contribution

Contributions are welcome under GPL-2.0-or-later. The checked source release for this page is 1.1.0.