Content Insights Tip #79 | Preventing WebP > PNG conversion in Sitecore EE

While working with Sitecore XM Cloud, I ran into an unexpected issue while serving WebP images through Experience Edge to our headless application. Even as the media item was of WebP format, Experience Edge returned a converted PNG, increasing the file size by nearly ten times. For businesses and the team, that's a problem that we needed to solve.

What happened?

When you configure a WebP asset in the Content Editor. When published through Experience Edge, the generated media URL includes transformation parameters such as h and w. The delivery service transforms the image and outputs a PNG, sometimes always times larger than the original WebP.

Why

Sitecore confirmed this behaviour is by design (for now): any time an image is resized or transformed, Experience Edge defaults to PNG unless a format is explicitly requested. A feature request (DP-4174) has been logged to improve this behaviour and allow WebP to be preserved automatically.

Workaround

Until that feature lands, the only way to force WebP is to add the format parameter yourself to the querystring: /-/media/project/your-image.webp?f=webp

Without the "?f=webp" part, the transformation will result in a PNG.

I've coded the following script that matches an asset when it's served either through XM Cloud or Experience Edge and is of the format WebP.

// Regular expression to match Sitecore Cloud domain patterns
const SITECORE_CLOUD_DOMAIN_REGEX = /^([a-z0-9-]+\.)*sitecorecloud\.io$/i;

// Query parameter name for image format optimization with Experience Edge
const PARAMETER_NAME = 'f';

// Query parameter value to request WebP format with Experience Edge
const PARAMETER_VALUE = 'webp';

/**
 * Check if the image is hosted on Sitecore Experience Edge.
 * 
 * @param url - The URL object to check
 * @returns true if the hostname matches Sitecore Cloud (Experience Edge) domain pattern
 */
const isSitecoreCloudImage = (url: URL): boolean => {
  return SITECORE_CLOUD_DOMAIN_REGEX.test(url.hostname);
};

/**
 * Checks if the image filename extensions is .webp
 * 
 * @param url - The URL object to check
 * @returns true if the pathname ends with .webp extension
 */
const isWebpImage = (url: URL): boolean => {
  const WEBP_EXTENSION = '.webp';
  return url.pathname.toLowerCase().endsWith(WEBP_EXTENSION);
};

/**
 * Appends the 'f=webp' query parameter to Sitecore Experience Edge image URLs.
 * Only processes HTTPS URLs that are hosted on Sitecore Cloud and have a .webp extension.
 * 
 * @param src - The source image URL to optimize
 * @returns The optimized URL with webp parameter or the original URL if no optimization is needed
 */
export const optimizeEdgeImageUrlWithWebp = (src?: string): string | undefined => {
  if (!src) {
    return src;
  }

  let url: URL;
  try {
    url = new URL(src);
  } catch (error) {
    console.error('Invalid URL:', src, error);
    return src;
  }

  // Only optimize Sitecore Cloud images with .webp extension
  if (!isSitecoreCloudImage(url) || !isWebpImage(url)) {
    return src;
  }

  // Add the webp optimization parameter
  try {
    url.searchParams.set(PARAMETER_NAME, PARAMETER_VALUE);
    return url.toString();
  } catch (error) {
    console.error('Failed to add webp parameter to URL:', src, error);
    return src;
  }
};