Serve the Perfect Image, Every Time

Image performance is a commerce problem

Images are often the largest assets on a commerce storefront. Product grids, PDP galleries, editorial modules, cart thumbnails, and Open Graph previews all need the same source image in different sizes and formats.

If those variants are created manually, the workflow breaks down quickly. Every product image becomes a set of derivatives to generate, store, name, sync, and invalidate. That is operational overhead, and it usually leads to storefronts shipping images that are larger than the layout actually needs.

Thor Commerce handles this at the media URL level.

The Storefront API returns a stable media URL. The storefront decides what size it needs for a given component, appends transformation parameters, and lets Thor’s image delivery layer generate and cache the optimized variant.

How it works

A product image returned from the Storefront API includes a src value:

The src is the source for optimized delivery. Your storefront appends the transformation parameters needed by the layout:

A rendered URL can look like this: https://cdn.thorcommerce.io/example-project/example.png?width=800&format=auto&quality=80

Thor normalizes the request, transforms the image, stores the generated variant, and serves it through the CDN. Equivalent requests are normalized into the same operation order, which improves cache reuse across storefront components. Explore the full image API reference

The image API is intentionally small:

width / w
height / h
format / f
quality / q
fit
dpr

width and height control the output dimensions. If only one dimension is provided, the image keeps its aspect ratio.

format controls the output format. Supported values include auto, jpeg, webp, avif, png, svg, and gif. For browser-rendered images, format=auto is usually the right default because Thor can choose the best supported format from the request.

quality controls lossy output quality from 1 to 100.

fit controls resizing behavior. Supported values are cover, contain, fill, inside, and outside.

dpr lets the storefront request higher-density assets without hardcoding separate dimensions. For example, width=400&dpr=2 is normalized to a width=800 transformation.

Why this matters

The storefront should not have to know how images are stored, transformed, or cached. It should only know what each component needs.

A product card might need a 400px image. A gallery might need 1200px. A mobile viewport might need different srcset candidates than a desktop viewport. Those are rendering decisions, so they belong in the component.

Thor keeps the source media stable and moves the expensive work into the delivery layer.

Recommended workflow

1. Query Media.src from the Storefront API.

2. Let each component define the sizes it needs.

3. Generate src and srcset URLs from those sizes.

4. Use format=auto for browser images.

5. Set an explicit quality for predictable output.

6. Keep original upstream storage URLs out of storefront templates.

The result is a clean contract: GraphQL provides the media reference, the storefront describes the desired output, and Thor’s CDN-backed image pipeline handles transformation and delivery.