GraphQL Compose Codegen

GraphQL Compose Codegen generates TypeScript types, GraphQL fragments, and React component stubs for Next.js frontends from your Drupal content model, so the frontend stays in sync with the schema.

This module is for Drupal sites that serve content to a separate frontend application — often called a "headless" or "decoupled" setup. If you're using the GraphQL Compose module to expose your content as a GraphQL API, this module handles the tedious next step: writing the TypeScript types and GraphQL queries the frontend needs to consume that data. When you add a content type, paragraph type, or field in Drupal, the module tells you exactly what to regenerate and produces ready-to-merge code so you don't write boilerplate by hand.

Features

The module adds four Drush commands and a set of admin integrations:

• drush gqcc:inspect — lists every node and paragraph bundle and the "extra" fields it adds beyond your shared base type, with their resolved TypeScript types.
• drush gqcc:generate — writes four scaffold artefacts per run: TypeScript type definitions, GraphQL inline fragments, a NodeRenderer switch-case file, and one React component stub per bundle.
• drush gqcc:diff — compares the current schema against the last generation, so you can see what changed before regenerating.
• drush gqcc:validate — verifies that the scaffold files on disk are in sync with the live schema. Exits non-zero, so it's safe to wire into CI or a pre-commit hook.
• Schema-change notices — when someone adds or removes a content type, paragraph type, or field via the Drupal admin UI, the module logs a notice at /admin/reports/dblog with the exact command to run.
• Full paragraph support — paragraph bundles produce their own type definitions, fragments, and component stubs alongside node bundles.
• Pluggable field-type mappers — other modules can register their own Drupal-field-type → TypeScript-type mappings via tagged plugins, so custom field types can be handled without patching this module.
• --dry-run, --allow-external, idempotent writes (no churn when nothing changed), and an output-dir safety guard that prevents accidental writes to dangerous filesystem locations.

Typical use cases:

• You maintain a Drupal site with a Next.js frontend (on next-drupal or a hand-rolled GraphQL client) and keep losing time hand-typing TypeScript shapes for every new field.
• Your editorial team adds content types and you want a single command that scaffolds the matching frontend files instead of doing it from memory.
• You want CI to fail when somebody forgets to regenerate types after a content-model change.

Post-Installation

1. Install with Composer and enable the module:

   composer require drupal/graphql_compose_codegen
   drush en graphql_compose_codegen

2. Visit Configuration → Development → GraphQL Compose Codegen (or /admin/config/development/graphql-compose-codegen) to set:

   • The name of your shared base TypeScript type (default NodeCommonFields)
   • The list of fields that already live in that shared base type, which are excluded from per-bundle output
   • A default output directory for generated files (relative to the Drupal root or absolute)

   The same values can also be set via drush config:set or by editing graphql_compose_codegen.settings.yml in your config sync directory.

3. From the command line, point the generator at your Next.js project root:

   drush gqcc:generate --output-dir=../ui

   The four scaffold artefacts land under {output-dir}/generated/. Review each file, then merge the pieces you need into your types/index.d.ts, your node-by-path query, your NodeRenderer.tsx, and your components/drupal/ directory. The generated files have a .generated suffix and are intentionally not referenced anywhere — delete them once you've integrated what you need.

4. Check /admin/reports/status for runtime checks (whether any node bundles exist, whether your configured base type fields actually exist on at least one bundle).
5. Check /admin/help/graphql_compose_codegen for a quick reference to the four commands.

Additional Requirements

• Drupal core 10.6, or 11.3+
• PHP 8.1 or higher
• GraphQL Compose 2.1 or higher (this module introspects its schema)
• Drush 12 or 13 — Drush is a hard dependency because the module's entire user surface is Drush commands

Recommended modules/libraries

These modules aren't required, but if they're enabled their field types are mapped automatically:

• Paragraphs — enables paragraph-bundle introspection and fragment generation
• Scheduler — publish_on / unpublish_on fields are mapped to TypeScript string
• Smart Date — smartdate fields are mapped to a SmartDate TypeScript type

Custom field types from any other module can be supported by writing a small FieldTypeMapper plugin. See graphql_compose_codegen.api.php for the hook and plugin documentation.

Similar projects

Several modules touch adjacent problems. None of them produce the same output for the same stack:

• TypeScript Definition Generator generates TypeScript types for Drupal's internal entity API (e.g. FieldItemList<IntegerItem>). This module generates the client-facing shape that GraphQL Compose actually returns over the wire.
• Next.js generator scaffolds Next.js components from JSON:API using the Drush Code Generator. This module is opinionated for GraphQL Compose instead, and produces TypeScript types and fragments alongside React components.
• GraphQL Compose: Fragments auto-generates GraphQL fragments and exposes them server-side in the schema's _info query. This module writes fragments to disk so you can paste them directly into hand-written queries, and also produces TypeScript types and React stubs.
• GraphQL Export exports the raw .graphqls schema or introspection JSON to disk for use with the npm graphql-codegen tool. The two are complementary — this module is opinionated about the GraphQL Compose + Next.js + React stack and emits ready-to-merge code, not raw schema.

This module is intentionally narrow in scope. If you're on a different decoupled stack (Vue, Svelte, Astro, JSON:API), one of the modules above will serve you better.

Supporting this Module

Bug reports, feature requests, and merge requests are welcome in the issue queue. Patches that add field-type mappers for popular contrib modules are especially appreciated.

Community Documentation

(None yet — links to walkthroughs, blog posts, and demo sites will be added here as they're published.)