GraphQL Compose drops text field cache tags: how to keep them
On a decoupled Drupal site using GraphQL Compose, editing a media item that is embedded in a body field may never refresh the pages that embed it. GraphQL Compose returns the processed HTML of a formatted text field as a plain string, so the cache tags the text filters collected (including the embedded media's) never reach the GraphQL response. The fix is a few lines in hook_graphql_compose_field_results_alter that add each text item's processed property as a cacheable dependency. If files can be replaced in place, you also need versioned image URLs, because a front-end image optimiser caches by URL.
What the symptom looked like
The site is a Drupal back end with a Next.js front end that fetches content over GraphQL and revalidates by cache tag when Drupal invalidates one. Editors embed media in body text with CKEditor 5, which stores a <drupal-media> element that the Embed media filter turns into rendered markup.
Editing the node itself refreshes the page, because the node's own cache tag is on the response. Editing only a media item that sits inside the body text does not: the page keeps showing the old version until something else invalidates the node.
Why the media cache tags went missing
In Drupal core, a formatted text item has a computed processed property. Behind it is Drupal\text\TextProcessed, which runs the text through its format's filters and implements CacheableDependencyInterface. The filters report their own cacheability as they go: Embed media adds the cache tags of every media entity it renders, and the same is true of any filter that renders entities. When Drupal renders the field itself, the render system bubbles those tags up to the page.
GraphQL Compose (this was version 2.4) resolves a text item to an array of its value, its format and its processed HTML, and the processed HTML is taken as a string. The string carries none of the metadata. So the GraphQL response for the node gets the node's own cache tags, plus those of anything resolved through a reference field, and nothing from the media inside the body. When the media is saved, Drupal invalidates media:42, nothing has that tag, and the cached GraphQL result and the front-end page stay as they were.
This is easy to miss in testing because node edits work, and most people test by editing the node.
How to put the cacheability back
GraphQL Compose has an alter hook that runs on every field it resolves. It receives the results, the entity being resolved from, the field type plugin, and the GraphQL FieldContext. FieldContext is a refinable cacheable dependency, so anything added to it ends up in the response's cache metadata.
<?php
use Drupal\Core\Entity\FieldableEntityInterface;
use Drupal\graphql\GraphQL\Execution\FieldContext;
use Drupal\graphql_compose\Plugin\GraphQLCompose\GraphQLComposeFieldTypeInterface;
/**
* Implements hook_graphql_compose_field_results_alter().
*/
function mymodule_graphql_compose_field_results_alter(array &$results, $entity, GraphQLComposeFieldTypeInterface $plugin, FieldContext $context) {
$definition = $plugin->getFieldDefinition();
if (!in_array($definition->getType(), ['text', 'text_long', 'text_with_summary'], TRUE)) {
return;
}
if (!$entity instanceof FieldableEntityInterface || !$entity->hasField($definition->getName())) {
return;
}
// The filters' cache tags (embedded media among them) live on the
// processed property, not on the string GraphQL Compose returns.
foreach ($entity->get($definition->getName()) as $item) {
$context->addCacheableDependency($item->get('processed'));
}
}
Asking TextProcessed for its cache tags makes it run the filters first when they haven't run yet, so this works whether or not the resolver has already read the value. The result is kept on the property object, so the text isn't filtered twice.
To check it, query the node, then look at the cache tags on the response (or in the GraphQL result cache): media: tags for each embedded item should now be there. Then edit only the media and confirm the page changes.
Why the image could still be stale after the fix
Cache tags fix the HTML. They don't fix the image file. Some sites let editors replace a media item's file in place so that existing links keep working, which keeps the same filename and therefore the same URL. The page now refreshes, but it points at a URL the front end has already seen.
The Next.js image optimiser caches its output by the source URL (plus width, quality and format). Ask it for the same URL and it serves the old optimised image. A CDN in front of the site does the same.
The fix is to make the URL change when the file changes. A file entity's changed timestamp updates when the file is replaced, so it makes a good version parameter:
<?php
use Drupal\file\FileInterface;
function mymodule_versioned_url(string $url, FileInterface $file): string {
$separator = str_contains($url, '?') ? '&' : '?';
return $url . $separator . 'v=' . $file->getChangedTime();
}
There are two places to apply it, and you need both:
- Image URLs returned through GraphQL, for images in image or media reference fields. These go through the same results alter hook as above, for image fields.
- Images Drupal renders itself, which is what media embedded in body text are. Those URLs are built by Drupal's own theme layer and arrive inside the processed HTML, so the GraphQL hook never sees them as URLs. A
hook_preprocess_imageimplementation that finds the file for the image and versions itssrccovers them.
On the Next.js side, if your images.remotePatterns entries set a search value, make sure it still matches URLs with the new parameter, or the optimiser will refuse them.
What I'd check on any decoupled Drupal site
The general lesson is that any value which leaves Drupal as a plain string has lost its cacheability, and GraphQL is a place where that happens quietly. Processed text is the obvious case because filters do real work (embedding media, rendering entity links, resolving tokens), but it applies to any custom resolver that returns rendered output as a string. When a field's freshness depends on other entities, the resolver has to pass their cacheability along.
I'd test it the way editors work rather than the way developers do: edit the thing that is embedded, not the page it's embedded in.
Key takeaways
- GraphQL Compose returns a formatted text field's processed HTML as a string, so the cache tags its filters collect are lost unless you add them back.
- Adding each text item's
processedproperty as a cacheable dependency inhook_graphql_compose_field_results_alterrestores the embedded media's cache tags on the GraphQL response. - Tag invalidation refreshes the HTML but not an image whose URL never changed, because the Next.js image optimiser and CDNs cache by URL.
- Appending the file entity's changed time as a query parameter makes replaced files get new URLs, both for images returned through GraphQL and for images Drupal renders inside text.
- Test cache invalidation by editing the embedded entity on its own, not the page that contains it.