Image optimization

Thor image optimization is exposed as a URL API on top of Storefront media.

The Storefront API returns media through the Media object. Its src field is a full CDN URL. Storefront code uses that URL as the base image URL and appends query parameters for the variant it needs in a specific layout.

The important boundary is:

• GraphQL tells your storefront which media exists
• Media.src gives you the CDN delivery URL
• query parameters on src describe the requested output
• the same URL can be used in img, picture, framework image components, CSS backgrounds, and Open Graph image generation

Add transformation parameters to the src URL returned by Storefront.

Supported parameters:

• width or w: output width in pixels
• height or h: output height in pixels
• format or f: auto, jpeg, webp, avif, png, svg, or gif
• quality or q: quality for lossy formats, capped at 100
• fit: cover, contain, fill, inside, or outside
• dpr: device pixel ratio multiplier for width and height

Use long parameter names in application code unless you need shorter URLs. They are easier to read in templates, logs, and browser devtools.

Build image URLs from the returned src instead of hardcoding CDN paths.

A typical product card asks GraphQL for the variant image, then derives the concrete render URLs in the storefront. Choose widths from the rendered layout, not from the original asset. For example, a product grid might use 400, 800, and 1200 pixel variants while a full-bleed product gallery might use larger values.

format=auto is usually the right default for browser-rendered images. The CDN resolves it to AVIF when supported, then WebP when supported, and JPEG otherwise.

Prefer srcset and sizes over a single large URL.

srcset lets the browser choose the smallest useful image for the viewport and device density. Keep every entry on the same Media.src and vary only the transformation parameters. This gives the CDN stable, reusable variants across product listing pages, collection pages, and product detail pages.

The CDN normalizes valid parameters before resolving the image.

Normalization means equivalent requests map to the same variant. Parameter names are lowercased, aliases are converted to their canonical operation, dpr is applied to width and height, and the operations are ordered consistently. Unknown or invalid parameters are ignored.

If no valid image operation is provided, the request resolves to the original media. If width or height is provided without fit, Thor keeps the original aspect ratio and does not enlarge the image.

A Thor storefront image URL is a Thor CDN URL with transformation parameters appended by the storefront.

For example:

https://cdn.thorcommerce.io/example-project/example.png?width=1920&format=webp&upscale=false

In storefront code, start from the Media.src value returned by GraphQL and add the supported Thor image parameters for the specific component. Avoid copying a fully transformed URL between templates, because the width, format, quality, and fit should come from the layout that renders the image.

The supported Thor optimization parameters are the ones listed above. Extra parameters from older templates, such as upscale=false, are not part of the storefront image optimization contract.