Consumer Image Styles for decoupled Drupal image delivery
Consumer Image Styles lets a headless front end request image derivatives that Drupal has already defined, so the front end gets the right size and crop from the JSON:API response without building image URLs by hand. Teams need it once editors keep uploading images in Drupal while Next.js or another framework renders the public site, and the front end has to choose between several sizes for each device. In a standard Drupal site, image styles are applied when Drupal renders a page. In a decoupled build, Drupal returns only data, so the question of which derivative is served, at what dimensions, and under which URL becomes a delivery design problem that someone on the team must own.
Start by listing the breakpoints and layouts the front end actually uses, then map each one to an image style that editors and developers agree on. Keep the number of styles small. Every additional style creates derivatives to generate, store and cache, and every change to a style affects images that already exist. Ask the project team to confirm in writing which image style names the front end will request, and who may add or change them. Editors should understand that a crop chosen in the media library may not match a layout the front end chose to show.
Before you commit to this module, check its project page on Drupal.org for the current release and the Drupal versions it supports, and confirm how it names and structures derivative data in its responses. Test those responses against your front end's image component in a staging environment, including how absolute URLs are built when media is served from a different host. Plan CDN caching for the image URLs from the start: confirm which URL patterns are stable, how long derivatives are cached, and how purging works after an editor replaces an image. Those checks set the operating cost of the image pipeline more than the module installation does.
Which image delivery pattern fits your front end
This table compares three ways to deliver images from Drupal to a decoupled front end: Drupal-generated derivatives through JSON:API, front-end transformation of the original, and an external image service or object storage behind a CDN. Read each row against your editors' needs, your breakpoint count and your front-end team's build setup. The main takeaway is that the pattern decides where image transformation work lives, so confirm ownership before the content model is fixed.
| Decision factor | Drupal derivatives via Consumer Image Styles | Front-end optimizer or image component | External image service or object storage with CDN |
|---|---|---|---|
| Where transformation runs | Drupal generates each derivative when a style is requested | The front end's build or request pipeline crops and resizes the original | A separate image service or pipeline generates variants from the stored original |
| Editor control | High: editors keep crops and focal points within Drupal's media workflow | Medium: editors upload originals, and crop rules live in front-end code | Medium to high, depending on whether the service exposes crop controls to editors |
| Breakpoint count | Suits a fixed, modest set of styles defined in Drupal | Suits many breakpoints that change often without Drupal configuration | Suits many breakpoints and formats, provided the service supports them |
| Front-end framework fit | Works with any client that reads JSON:API image URLs | Best where the framework has a built-in image component | Works with any client that can build image URLs from a template |
| Hosting constraints | Drupal must serve or cache derivative files, so web and file storage capacity matter | Requires a runtime or build step that can process images | Needs an account with the service and object storage in an approved location |
| What your team maintains | Consumer Image Styles configuration, style naming and the JSON:API response shape | Image component code, sizing rules and any server-side optimizer | Service configuration, storage buckets, CDN rules and URL signing if used |
| Cache purging | Derivative URLs and CDN rules must be purged when originals or styles change | Usually handled by front-end build or revalidation, with CDN rules set separately | Cache keys and invalidation are set by the service and CDN, so confirm purge behavior |
| Confirm with the front end team | Which style names and sizes they need, and whether they read derivative URLs directly | Whether the framework's image component supports remote sources and the Drupal domain | Whether URLs must be signed, which formats are required and where the CDN sits |
Designing image styles for editors, breakpoints and crops
The number of image styles, the breakpoints they cover, the crop rules and the output formats decide how much work editors do and how much the front end has to choose from. Each image style produces a derivative for every upload that is used with it, so the design is a set of trade-offs rather than a single correct answer. Start from the layouts the front end actually renders, list the image slots on each component, and group slots that share an aspect ratio and approximate width. That list usually shows how many derivatives the site needs before any module is configured.
Many specific derivatives give the front end precise sizes and reduce the bytes sent to each device, but they multiply storage, processing time and the number of crops an editor must trust. Fewer general derivatives are easier to explain to editors and cheaper to regenerate, yet the front end then serves images that are larger or cropped less precisely than the design intends. A common middle ground is a small set of aspect ratios, each with a few widths, and a responsive srcset built by the front end from those widths. Confirm in the Consumer Image Styles documentation how it exposes derivative URLs and dimensions, and whether the front end can request a style by name or must receive every variant.
Editors upload originals that rarely match the aspect ratio a layout needs. Focal point or manual crop settings decide where the crop is anchored, and those settings are only as good as the editorial guidance behind them. Decide which slots accept a manual crop, which fall back to a focal point, and what happens when neither is set. Write the rule down for editors, including minimum upload dimensions, so that a small image is flagged at upload time rather than producing a soft derivative on a large screen. Check with the module's documentation how the crop data is stored and whether it is applied per style or per field. A change to an image style does not usually rewrite images already in use. Derivatives are generated on demand or on a schedule, so a changed width, crop or format may apply only to new requests or after a flush, and old URLs may keep serving previous output until caches expire. Plan the change as a release step: test the new style on representative images, flush the image style and CDN caches for the affected paths, and confirm the new URLs before retiring any old style. Ask the team that owns the CDN which purge scope it supports, because purging every image on a large site has its own cost.
Setting up derivatives, JSON:API output and cache rules
This sequence takes a Drupal site from a supported core version to a JSON:API response that serves responsive image derivative URLs, with checks that confirm each breakpoint renders and that replaced images produce new URLs. It produces a tested configuration the front end can rely on.
Confirm the Drupal version and hosting baseline
The team confirms the site runs a Drupal version that is still receiving security coverage, with a PHP version the release supports, and that the web server and database are in the supported list. Drupal 11 is the current major version, and Drupal 10 reaches end of life on December 9, 2026, so a site on Drupal 10 should plan its move before that date. Done means the site status report shows no blocking errors and the team has written down the core, PHP and database versions it will test against.
Install and enable the module with its dependencies
A developer adds the Consumer Image Styles module with Composer, enables it and any dependencies it lists on its Drupal.org project page, and records the exact release in the project's lock file. Confirm the release notes state support for your Drupal core version before installing. Done means the module appears as enabled in the extension list, the status report is clean, and the change is committed to version control rather than made only in the database.
Define image styles for each breakpoint
An editor or developer, working with the front end team, lists the breakpoints the design needs and creates one image style per crop, ratio and width combination in the Drupal image style configuration. Keep the set small, since each style produces its own derivative. Confirm the exact screens and keys for linking image styles to consumers on the module's project page. Done means each style previews correctly on a test image and the list matches the breakpoints in the design file.
Expose the media or image resources in JSON:API
A developer checks that the JSON:API resources for the media type or image field are enabled and that the image field returns the file and metadata the front end needs. Where the default output lacks the derivative data, the team adds the consumer image style mapping on the field. If JSON:API Extras is in use, confirm the field is not hidden. Done means a request to the media or node endpoint returns the image field with the expected attributes for a sample entity.
Verify derivative URLs in a JSON:API response
The developer requests a sample entity with an authenticated or anonymous request, depending on how the front end reads content, and inspects each derivative URL in the response. Each URL should point at the Drupal origin or the intended file host, return an image with the expected dimensions, and include the style name the front end will request. Done means every breakpoint has a working URL and the response shape matches the field names and nesting in the front end's type definitions.
Test that the front end renders each breakpoint
The front end team points a staging build at the configured endpoint and checks each breakpoint in a responsive viewport, confirming the browser downloads the expected derivative and that no broken image or missing srcset entry appears. They also confirm the image dimensions match the layout so the page does not shift. Done means a recorded test run shows every breakpoint loading the correct file with no console errors related to images.
Confirm replaced images produce new URLs
An editor replaces an image on a test entity and the team checks the JSON:API response again. The derivative should come from the new file, and the URL should change so that CDNs and browsers stop serving the previous version. If the URL stays the same, the cache rules need review. Done means the old and new URLs are both recorded, the new URL returns the replacement image, and the team has noted how long stale copies persist at the CDN.
Set CDN cache rules for image URLs
The operations team configures the CDN or reverse proxy to cache derivative URLs for the lifetime the team agrees on, and to purge them when files change, using the purge mechanism of the chosen CDN. Test with a request through the CDN and confirm the response headers show caching and the origin is not hit on repeat requests. Done means a cache hit is confirmed for a derivative, and a purge test removes the stale copy as expected.
CDN caching for image URLs by hosting setup
In this model, the browser requests image derivative URLs from the CDN, which forwards cache misses to Drupal. Drupal generates derivatives through Consumer Image Styles on first request or during image style flushes, then serves them from the public files directory. Because the CDN caches the response, the derivative URL becomes the unit of caching, and its path must stay stable for as long as the image content is unchanged.
- Derivative URL stability: Consumer Image Styles produces URLs that include the style name and a hash of the source file. A replaced file produces a new path, which bypasses old cache entries without purging them.
- Deleted images: A deleted file returns a not-found response from Drupal. Confirm how the CDN caches 404 responses and for how long.
- Cache tag purging: If the CDN supports cache tag purging from Drupal, configure the image entity and file tags so that metadata changes such as alt text or focal point updates clear cached JSON:API responses that embed image URLs.
- Headers to confirm: Check the Cache-Control and Vary headers that Drupal sends for files and JSON:API responses, and whether the CDN honors them.
- Vendor and hosting checks: Ask the CDN vendor which purge APIs and tag headers it accepts, and ask the hosting team whether Drupal's public files path is reachable only through the CDN.
Confirm the purge and header behavior in a staging environment before the first production image change.
In this model, derivatives or original files are written to an object storage bucket, and the CDN serves them directly from the bucket origin. Drupal still generates derivatives, but the front end receives URLs that point at the CDN hostname, not at Drupal. Caching is therefore governed by the bucket object keys, object metadata and the CDN origin settings, which can differ from what Drupal sends.
- Object keys as cache keys: Replacing an image with the same object key keeps the same URL. Plan whether replaced files get new keys, which is the simpler path, or whether the CDN must be purged for each replaced key.
- Explicit purge jobs: Deleting an object in the bucket does not remove it from CDN edge caches. Add a purge step to the deletion workflow for each affected path.
- Object metadata: Confirm which Cache-Control value the bucket stores on each object, since Drupal's response headers do not apply to direct bucket reads.
- Origin access: Confirm that the bucket is reachable only from the CDN, and that signed or private URLs, if used, are generated with an expiry that matches the cache lifetime.
- Vendor and hosting checks: Ask the CDN vendor how it handles object key changes and invalidation quotas, and ask the hosting team who owns bucket lifecycle rules and whether they can delete old derivatives.
Illustrative case: a derivative written under a fixed key remains cached at the edge after the source image changes until the purge job runs.
In this model, the front end framework hosts the site and runs its own image optimizer, which fetches source images from Drupal, transforms them and caches the results at the framework or hosting platform. Drupal supplies the original or derivative URLs, but the public image URLs seen by visitors are issued by the front end. Invalidation therefore depends on the framework's build, revalidation and image cache behavior, not only on Drupal.
- Source URL fetched by the optimizer: Confirm which Drupal URL the optimizer requests, and whether it sends authentication headers when the Drupal files are not public.
- Optimizer cache lifetime: Confirm how long optimized variants are kept, whether they are keyed on the source URL and whether a changed source with the same URL is detected.
- Revalidation on content change: Confirm how the framework revalidates pages and images when Drupal publishes a change, such as through a webhook or a time-based rebuild.
- Deleted images: A removed source returns an error to the optimizer. Confirm whether the framework serves stale copies in that case and for how long.
- Vendor and hosting checks: Ask the hosting provider how image optimization is billed and capped, and confirm the cache headers the platform sends with optimized images.
Test a replaced image end to end, including the edge cache, before you rely on any single invalidation step.
Security risks in public image URLs and derivative generation
Image derivatives sit at the edge of a decoupled build, where Drupal's access checks, the CDN and the front end all touch the same file. The cards below cover the places where a restricted original can leak through a public URL, a generated size or cached copy, and the update routines that keep the image pipeline patched.
Derivatives exposed on public URLs
Drupal serves derivatives from a public file path once they are generated, so a restricted original can still be reachable through its style URL if the source file was never private. Confirm which file system each media field stores its originals on, and whether private files are served only through Drupal's access checks. Test the derivative URL of a restricted image while logged out, not just the original.
Access control not carried into derivatives
Media access rules belong to the entity, but a derivative URL is a plain file path that the CDN and browser will fetch without asking Drupal. When a CDN caches an image after an editor unpublishes the node, the old file can keep serving. Ask the team to map each media entity to its access rule and confirm how the CDN honors revocation.
Unbounded derivative generation
Image style URLs can carry a style name and token, and a front end that builds sizes from user input can ask Drupal to create many derivatives. Each new size consumes CPU, storage and cache space. Restrict the styles exposed to consumers to a fixed list, reject unknown style names at the API layer, and review which parameters the front end forwards.
Metadata leaking from uploads
Photos from cameras and phones often contain EXIF data such as capture time, device model and GPS coordinates. Image styles that resize a file do not remove that metadata unless the derivative pipeline strips it, so the leak can reach public URLs. Confirm with the content team whether location data is captured, and test a derivative with an exif reader before launch.
Cache poisoning and stale images after edits
A CDN can store an image under a URL that the front end built with unexpected headers or query strings, and then serve that copy to every visitor. After an editor replaces an image, an old derivative may remain cached under the same path. Confirm how cache keys are formed, which headers vary the response, and how purging follows media updates.
Contributed module advisories
Image handling depends on Drupal core and contributed modules, and advisories for those projects arrive on the Drupal Security Team's schedule. A vulnerable module left in place can expose the image pipeline even when the site configuration is correct. Ask who monitors advisories, how fast a security release is applied, and whether the test environment runs the same versions as production.
What to confirm before estimating the build
Effort for decoupled image delivery depends less on the module itself than on how many images your content model carries and how those images are stored today. Start by counting the content types that hold image fields, the media types they reference, and whether any image is used in more than one place. Each distinct image field in JSON:API needs its own derivative mapping for Consumer Image Styles, and each one needs a front end component that requests the right sizes. Ask whether images are public or private. Public files can be served through a CDN with predictable URLs, while private files need signed or authenticated delivery, which changes both the caching design and the access checks your front end must pass.
Next, establish what already exists. A established media library with clean alt text, consistent file naming and reusable media entities is far cheaper to expose than a library full of unmanaged uploads. If you are migrating from another Drupal site or a CMS, confirm how image files and their references will be carried across, because the migration decides whether derivatives must be regenerated and whether old URLs need redirects. Check whether the front end framework already has an image component that accepts width, height and srcset values. If it does, the work shifts toward matching its expectations; if not, the team will build that layer, and that work belongs in the estimate.
Finally, confirm who owns the CDN and who owns the origin. When one team runs both, cache keys, purge rules and image URL formats can be agreed in one conversation. When they are split, every change to derivative URLs or cache headers needs coordination, and purging after an editor replaces an image becomes a cross-team process. Before you ask for a quote, verify the current Consumer Image Styles project page on Drupal.org for supported Drupal core versions, confirm the Drupal core version in use against the Drupal core release schedule, and check how your chosen framework's image handling generates and caches optimized images.
Questions teams ask before building image delivery for decoupled Drupal
What does image delivery for decoupled Drupal cost, and what drives it up or down?
The cost depends mostly on how many image types, breakpoints and front ends you need, and on how much of the front end image handling is already built. A quote should separate the Drupal side (Consumer Image Styles configuration, JSON:API output, any custom field or resource changes) from the front end side (how components request and render responsive sources) and from CDN configuration. Work is mostly one-time setup, with a smaller recurring cost for adding new image styles, changing breakpoints or reviewing caching after releases. Ask each bidder to list which items are included, who writes the front end code and who owns CDN rules.
How long does an image delivery setup usually take?
Duration follows the number of content types with images, the number of distinct derivatives per image and whether the CDN and front end teams are ready. A single front end with a small set of image styles is a much shorter piece of work than several front ends sharing one media model with art direction and focal points. The main delays come from unclear breakpoint decisions and from waiting for CDN access or change windows. Ask for a timeline that lists the dependencies as separate milestones so you can see where time is lost.
What must our team provide before the work starts?
Plan to provide the following before the build begins:
- Sample content that includes the widest range of image sizes, aspect ratios and focal points your editors will upload.
- A written list of breakpoints and the layouts each one serves, agreed with the front end team.
- Access to the CDN configuration or a named contact who can change caching rules and purge image URLs.
- A front end contact who can confirm how components request sources and which formats the browsers in your audience need.
- A staging environment that mirrors production hostnames so cached URLs behave as they will at launch.
Can our internal team deliver image handling without a partner?
Yes, if your team already runs Drupal, understands JSON:API and has someone who owns the front end image components. Consumer Image Styles is a contributed module on Drupal.org, so the configuration is within reach of a capable Drupal developer. The partner case is stronger when several front ends share one media model, when CDN rules are complex or when the team has no time to test caching behavior before a launch. Compare the internal plan against a written scope so the gaps are visible before anyone commits.
How do we test image changes before they reach production?
Test at three levels. First, check the JSON:API responses in staging to confirm each derivative URL, width, height and format is present for sample images. Second, load the front end in the browsers and screen sizes your audience uses and confirm the right source loads for each breakpoint. Third, change an image on a staging node, purge its URL at the CDN and confirm the new version appears everywhere without stale copies. Keep the sample content set so the same checks can run again after each release.
How does image work fit into ongoing Drupal updates?
Image styles and derivative URLs can change when Drupal core or contributed modules are updated, so each update window should include a regression pass over the sample content. Check that JSON:API responses still expose the derivatives your front end expects and that the CDN still caches and purges them correctly. Drupal core bugfix releases come out on the first Wednesday of each month and security releases on the third Wednesday, so plan a recurring test slot around those dates. Ask any partner how the image checks are documented so your own team can repeat them.
Limits to confirm in your environment
Consumer Image Styles sits between Drupal's media handling, JSON:API and your CDN, so its limits show up at each boundary. The checks below are questions to put to the module's maintainers, your front end vendor and your own platform team before you write the build plan.
Supported Drupal core versions
Read the supported core versions on the module's Drupal.org project page and match them to the Drupal version you run now and the one you plan to move to. Ask the maintainers whether they test against each minor release and how long they keep older branches open. A module that trails core will block your upgrade path, so confirm this before the front end is designed around it.
JSON:API and front end compatibility
Confirm that the module exposes derivative URLs in the JSON:API responses your front end reads, including nested paragraph or media references. Test with the exact JSON:API Extras configuration and the image loader your framework uses, since renamed fields or altered resource paths can silently drop the derivative list. Ask the maintainers which combinations they have tested.
Image formats and file storage
Check how derivatives behave for each format your editors upload, such as JPEG, PNG, WebP and AVIF, and whether the module generates every breakpoint you need. Then confirm the behavior on your file storage, whether local disk, network file system or object storage, because derivative generation and public URL signing differ by backend. Test with real editorial uploads, not sample files.
CDN purge and cache tags
Ask your CDN provider whether it can purge individual image URLs or cache tags when an editor replaces a file or changes crop settings. Derivative URLs are often reused across pages, so a purge that misses one variant leaves stale crops live. Agree the purge trigger, the hostname used for image URLs and the expected cache lifetime for generated files before launch.
Private media handling
Determine whether any images must stay behind authentication. Public derivative URLs are generally cacheable, but private media usually needs signed or access-checked delivery, which changes both the caching design and the front end's image loading. Ask the maintainers whether the module supports private files, and if not, plan a separate delivery path before you model content access.
Maintenance and release health
Review the project's release history, open issue queue and how the maintainers respond to security advisories through the Drupal Security Team. Ask who owns the module if the maintainers step back, and whether your team or a partner will carry patches. Budget for ongoing review of each core and module release, since this module sits on the image path that every page depends on.
How DeployOpen works on this
DeployOpen plans, builds, documents and supports decoupled image delivery for Drupal inside your own infrastructure. We start with the image styles your front end needs, then build and hand over the Drupal side, with the CDN and caching rules agreed in the same written scope.
How we scope
- Inventory every front end that consumes Drupal images and the breakpoints, aspect ratios and formats each one needs.
- Agree which Consumer Image Styles, JSON:API fields and CDN cache rules are in the written scope before work starts.
- Confirm with your team which image sources, storage backends and hosting constraints apply to your environment.
How we build
- Configure Consumer Image Styles and expose derivative URLs through JSON:API, with JSON:API Extras changes kept in version control.
- Set image URL and cache headers so the CDN caches derivatives and purges them when editors replace media.
- Test derivative generation, cache hit behavior and purge events on a staging environment that mirrors production.
How we hand over
- Document each image style, its consumers, its URL pattern and the expected cache lifetime for your team.
- Walk your developers and editors through how to add a breakpoint and how image changes reach the CDN.
- Deliver configuration, test scripts and runbooks in a form your own team can review and change.
How we support
- Keep Drupal, Consumer Image Styles and related contributed modules current through an agreed update routine.
- Offer ongoing support and continuous testing as a retainer if your team wants DeployOpen to stay on the work.
- Review image delivery after Drupal core and module updates, since release timing follows the published core schedule.
