GraphQL Compose
Toolkit for generating GraphQL schemas in Drupal, providing an extendable no-code GraphQL schema for Drupal GraphQL module.
graphql_compose
Overview
GraphQL Compose is a comprehensive toolkit for generating GraphQL schemas in Drupal. It provides an extendable no-code GraphQL schema for Drupal's GraphQL 4.x/5.x module, aiming to deliver a simple to use and simple to understand schema without too many "Drupalisms".
The module automatically generates a GraphQL schema from Drupal entities and fields through a plugin-based architecture. It supports over 50 field types out of the box and provides support for nodes, media, taxonomy terms, users, paragraphs, and more through optional submodules.
Key architectural features include: per-server configuration allowing each GraphQL server to have independent settings, cursor-based pagination through the Edges submodule, routing and URL resolution, menu support, Layout Builder integration, and extensive hook system for customization.
Features
- Automatic GraphQL schema generation from Drupal entities without writing code
- Plugin-based architecture with 54+ field type handlers, 8+ entity type handlers, and 30+ schema type definitions
- Per-server configuration - each GraphQL server can have independent GraphQL Compose settings
- Cursor-based pagination support through Connection/Edge pattern (via graphql_compose_edges submodule)
- Content routing and URL resolution with support for path aliases and redirects
- Menu system integration exposing Drupal menus as GraphQL queries
- Layout Builder and Layout Paragraphs support for complex page layouts
- Multilingual support with language inflection for singularization/pluralization in 7 languages
- Image style derivatives support for responsive images
- Block content exposure including custom blocks and plugin blocks
- Comments support with mutation for creating comments
- Views integration for filterable and sortable GraphQL queries
- Metatag module integration for SEO metadata
- Entity Construction Kit (ECK) support for custom entity types
- User information exposure with roles and status
- Extensive hook system allowing customization of schema generation, field resolution, and type definitions
- Copy UUID entity operation added to enabled entity types for easy reference
Use Cases
Headless Drupal with React/Vue/Next.js
Use GraphQL Compose to expose your Drupal content to a JavaScript frontend framework. Enable the entity types and fields you need, use the routes submodule to resolve URLs to content, and the edges submodule for paginated lists. The schema automatically updates when you add new content types or fields.
Mobile App Backend
Expose Drupal content to native mobile applications via GraphQL. Enable entity ID exposure for offline sync, use image styles for optimized mobile images, and leverage the user submodule for authentication. The simple queries option provides cleaner API for mobile developers.
Multi-site Content API
Use per-server configuration to create different GraphQL APIs for different consumers. Create separate GraphQL servers with different entity/field configurations, endpoint paths, and access controls for each client application.
Content Preview System
Use the routes submodule with entity preview buffer to build content preview systems. The module handles draft content resolution and language-specific previews for editorial workflows.
Complex Page Building
Combine Layout Builder or Layout Paragraphs submodules to expose complex page structures. The schema represents sections, regions, and components allowing frontends to render flexible page layouts defined in Drupal.
E-commerce Product Catalog
Expose product content types with their fields, images with multiple image styles for different display contexts, and taxonomy terms for categories. Use Views integration for filtered/sorted product listings with pagination.
Multilingual Content Delivery
Leverage built-in language support to serve content in multiple languages. The language context flows through all resolvers, and the inflector service handles proper pluralization for non-English languages.
Tips
- Use the 'Copy UUID' operation added to entity dropbuttons to easily get entity UUIDs for testing queries
- Enable 'Simple entity queries' to reduce schema complexity - instead of separate nodePage, nodeArticle queries, you get a single node query returning a union
- Use the GraphQL Explorer at /admin/config/graphql/servers/{server}/explorer to test queries interactively
- The info query provides schema version and custom settings - use it for cache invalidation and feature flags
- When developing, check the 'development' parameter in graphql_compose.services.yml for debugging options
- Custom settings in the Information form support Drupal tokens when the Token module is installed
- The inflector supports 7 languages - set the appropriate language for your primary content language to get correct pluralization
- Use hook_graphql_compose_field_results_alter() to transform field values before they reach the client
- Each GraphQL server can have independent GraphQL Compose configuration - use this for versioned APIs or different client needs
Technical Details
Admin Pages 3
/admin/config/graphql/servers/manage/{graphql_server}/graphql_compose
Configure which Drupal entity types, bundles, and fields are exposed via GraphQL. This is the main configuration page where you enable/disable specific content types, taxonomy vocabularies, media types, and their individual fields for GraphQL exposure.
/admin/config/graphql/servers/manage/{graphql_server}/graphql_compose/info
Configure schema metadata and site information that is exposed via the GraphQL 'info' query. This includes version information, site name, slogan, and custom key-value pairs.
/admin/config/graphql/servers/manage/{graphql_server}/graphql_compose/settings
Configure general behavior settings for GraphQL Compose including entity handling, field options, and string inflection rules.
Hooks 18
hook_graphql_compose_print_types
Add custom GraphQL types to the schema. Called during schema generation to register new ObjectType, InterfaceType, EnumType, or other GraphQL type definitions.
hook_graphql_compose_print_extensions
Add extensions to existing GraphQL types. Use this to add new fields to Query, Mutation, or any existing type in the schema.
hook_graphql_compose_singularize_alter
Alter the result from language singularization. Customize how bundle names are converted to singular form for GraphQL type naming.
hook_graphql_compose_pluralize_alter
Alter the result from language pluralization. Customize how type names are converted to plural form for collection queries.
hook_graphql_compose_field_enabled_alter
Change the enabled state of a field. Use this to programmatically hide or show fields in the GraphQL schema regardless of admin configuration.
hook_graphql_compose_field_results_alter
Alter results from field resolution. Modify, filter, or completely replace the data returned for a specific field.
hook_graphql_compose_entity_interfaces_alter
Add custom interfaces to entity types. Use this to add shared interfaces across entity types based on common fields or behaviors.
hook_graphql_compose_entity_bundle_enabled_alter
Change the enabled state of an entity bundle. Use this to programmatically include or exclude entity bundles from the GraphQL schema.
hook_graphql_compose_entity_base_fields_alter
Modify the base fields available for an entity type. Add or remove base fields before they are processed for GraphQL exposure.
hook_graphql_compose_entity_type_form_alter
Alter the entity type configuration form. Add custom settings to the GraphQL Compose Schema form for entity bundles.
hook_graphql_compose_field_type_form_alter
Alter the field type configuration form. Add custom settings to the GraphQL Compose Schema form for individual fields.
hook_graphql_compose_entity_translate_alter
Override entity translation behavior. Customize how entities are translated when resolved in a specific language context.
hook_graphql_compose_current_language_alter
Override the language resolution for field context. Customize which language is used when resolving multilingual content.
hook_graphql_compose_routes_incoming_alter
Modify URL paths before route resolution. Transform or normalize paths before they are resolved to entities.
hook_graphql_compose_routes_union_alter
Resolve custom route types. Map route values to specific GraphQL types for the RouteUnion.
hook_graphql_compose_edges_alter
Modify edge connections for entities. Customize pagination, filtering, or sorting of entity collections.
hook_graphql_compose_blocks_union_alter
Resolve custom block types. Map block plugin values to specific GraphQL types for the BlockUnion.
hook_graphql_compose_metatags_union_alter
Resolve custom metatag types. Map metatag values to specific GraphQL types for the MetaTagUnion.
Troubleshooting 7
Clear GraphQL caches by clicking 'Save configuration' on any GraphQL Compose form, or run 'drush cr'. The module automatically clears caches when configuration changes.
Ensure the entity type has a GraphQL Compose entity type plugin. Core types (node, media, taxonomy_term, user, paragraph) are supported. For other types, enable appropriate submodules (graphql_compose_blocks for block_content, graphql_compose_eck for ECK entities).
Check if a field type plugin exists for your field. The module supports 54+ field types. For unsupported fields, implement hook_graphql_compose_print_types() and hook_graphql_compose_print_extensions() to add custom handling.
GraphQL Compose respects Drupal's access control. Check entity access permissions, ensure 'exclude_unpublished' setting matches your needs, and verify the querying user has appropriate permissions.
Ensure referenced entities are published (if exclude_unpublished is enabled), the referenced entity type/bundle is enabled in GraphQL Compose, and the user has access to view the referenced entities.
Enable the graphql_compose_edges submodule for cursor-based pagination. Without it, entity reference fields return flat arrays without pagination support.
Enable the graphql_compose_routes submodule and ensure the entity bundle has 'Enable route loading' checked in the Schema form. Verify path aliases are configured correctly in Drupal.
Security Notes 7
- By default, entity IDs are not exposed to prevent enumeration attacks. Only enable 'Expose entity IDs' if your application requires numeric IDs.
- The module respects Drupal's entity access system. Users can only query content they have permission to view.
- When using the comments submodule with mutations, input is sanitized for XSS but ensure your application validates user input appropriately.
- The 'Exclude unpublished entities' setting provides defense-in-depth by hiding unpublished content even from users who might have view permissions.
- SVG embedding has a file size limit to prevent denial of service from large SVG files. Adjust the limit based on your needs.
- GraphQL introspection is enabled by default. Disable it in production if you don't want schema exposure.
- The routes submodule normalizes incoming paths - implement hook_graphql_compose_routes_incoming_alter() to add additional path validation if needed.