fix(cms-base-layer): proper image sizes (#2389)

Author: mkucmus

.changeset/frank-yaks-fry.md

@@ -0,0 +1,5 @@
+---
+"@shopware/cms-base-layer": patch
+---
+
+Fix product card and CMS image sizing to prevent duplicate/oversized image requests. Move fixed dimensions and `densities="1x"` into the `productCard` preset, and use `useElementSize`-based `width`/`height` props for `CmsElementImage`.

packages/cms-base-layer/AGENTS.md

@@ -395,12 +395,47 @@ Set `format` or `quality` to `undefined` to omit that parameter. Requires remote
 
 ## Responsive Image Architecture
 
-CMS images use a provide/inject pattern for responsive sizing:
+### Product Card Images (`SwProductCardImage`)
 
-1. **`CmsGenericBlock`** counts slots, calls `provide("cms-block-slot-count", slotCount)` and `provide("cms-image-sizes", getImageSizes(slotCount, appConfig.imageSizes))`
-2. **`CmsElementImage`** calls `inject("cms-image-sizes", "100vw")` and passes it to `<NuxtImg :sizes="...">`
-3. If media has thumbnails → native `srcset` from `getSrcSetForMedia()`. If not → synthetic `srcset` via `generateCdnSrcSet()` from `@shopware/helpers`
-4. **`useLcpImagePreload`** scans CMS sections for the first image and injects `<link rel="preload" as="image" fetchpriority="high">` during SSR
+The `productCard` preset only defines URL modifiers (format/quality/fit). `width`/`height`/`densities`/`loading` must stay on the component — NuxtImg presets don't propagate these reliably:
+
+```ts
+// nuxt.config.ts
+productCard: {
+  modifiers: { format: "webp", quality: 90, fit: "cover" },
+}
+```
+
+```vue
+<NuxtImg preset="productCard"
+  :src="coverSrcPath"
+  width="400" height="400"
+  densities="1x"
+  loading="lazy" />
+```
+
+- Fixed `width`/`height` (400) avoid hydration mismatches caused by dynamic DOM measurement
+- `densities="1x"` prevents duplicate retina requests
+- `loading="lazy"` defers off-viewport images
+
+> **Note:** Avoid adding `decoding` or `sizes` props on the component — they've caused Vue hydration attribute mismatches with NuxtImg, which trigger duplicate image requests.
+
+### CMS Images (`CmsElementImage`)
+
+CMS images use `useElementSize()` to measure the rendered container and pass the size to NuxtImg via `width`/`height` props:
+
+```vue
+<NuxtImg :width="imageSize" :height="imageSize" :src="imageAttrs.src" loading="lazy" />
+```
+
+- Returns `undefined` during SSR (no image fetched until client measurement)
+- After hydration, `useElementSize()` measures the container and NuxtImg fetches the correctly sized image
+- The size is multiplied by 2 (for retina) and rounded up to the nearest 100px
+
+### Other patterns
+
+1. **`CmsGenericBlock`** counts slots, calls `provide("cms-block-slot-count", slotCount)`
+2. **`useLcpImagePreload`** scans CMS sections for the first image and injects `<link rel="preload" as="image" fetchpriority="high">` during SSR
 
 ### Type Declarations
 

packages/cms-base-layer/README.md

@@ -372,68 +372,48 @@ The preload URL includes the optimized `format` and `quality` parameters from `a
 
 ## Responsive CMS Images
 
-CMS image elements (`CmsElementImage`) automatically serve appropriately-sized images using responsive `srcset` and `sizes` attributes. This prevents the browser from downloading images larger than their displayed dimensions — a common Lighthouse performance issue.
+Images are optimized to prevent the browser from downloading images larger than their displayed dimensions — a common Lighthouse performance issue.
 
-### How it works
-
-1. **`CmsGenericBlock`** counts the number of slots in each block, `provide`s a responsive `sizes` value (e.g., a 2-slot block means images are ~50% viewport width on desktop), and `provide`s the slot count via `cms-block-slot-count` for slider SSR breakpoint scaling.
-2. **`CmsElementImage`** `inject`s the sizes hint and applies it to `<NuxtImg>`.
-3. If the media has **pre-generated thumbnails** from Shopware, the existing `srcset` from thumbnails is used.
-4. If **no thumbnails** exist, a synthetic `srcset` is generated using CDN width-based resizing (`?width=400`, `?width=800`, etc.) via the `generateCdnSrcSet` helper from `@shopware/helpers`.
-5. **Slider components** (`CmsElementProductSlider`, `CmsElementCrossSelling`) `inject` the slot count to scale their SSR breakpoints — ensuring media queries account for the container being a fraction of the viewport (e.g., a 2-slot block doubles the breakpoint thresholds).
-
-The browser combines `sizes` + `srcset` to download only the image size it actually needs — during HTML parsing, before any JavaScript runs.
-
-### Configuration
+### Product Card Images (`SwProductCardImage`)
 
-Default slot-count-to-sizes mappings are set in `app.config.ts` and can be overridden:
+The `productCard` preset only defines URL modifiers (format/quality/fit). `width`/`height`/`densities`/`loading` stay on the component — NuxtImg presets don't propagate these reliably:
 
 ```ts
-export default defineAppConfig({
-  imageSizes: {
-    // slot count → sizes attribute value
-    1: "(max-width: 768px) 100vw, 100vw",   // full-width blocks
-    2: "(max-width: 768px) 100vw, 50vw",    // two-column blocks (e.g., image-text)
-    3: "(max-width: 768px) 100vw, 33vw",    // three-column blocks
-    default: "(max-width: 768px) 50vw, 25vw", // 4+ columns
-  },
-});
+// nuxt.config.ts
+productCard: {
+  modifiers: { format: "webp", quality: 90, fit: "cover" },
+}
 ```
 
-For example, to cap image sizes at a fixed pixel width for boxed layouts:
-
-```ts
-export default defineAppConfig({
-  imageSizes: {
-    1: "(max-width: 768px) 100vw, 1200px",
-    2: "(max-width: 768px) 100vw, 600px",
-    3: "(max-width: 768px) 100vw, 400px",
-    default: "(max-width: 768px) 50vw, 300px",
-  },
-});
+```vue
+<NuxtImg preset="productCard"
+  :src="coverSrcPath"
+  width="400" height="400"
+  densities="1x"
+  loading="lazy" />
 ```
 
-### Per-block override
+- **Fixed `width`/`height`** (400px) — avoid hydration mismatches caused by dynamic DOM measurement
+- **`densities="1x"`** — prevents duplicate retina requests
+- **`loading="lazy"`** — defers off-viewport images
 
-Individual block components can override the sizes value by calling `provide("cms-image-sizes", "custom value")` — this takes precedence over the default from `CmsGenericBlock`.
+> **⚠️ Avoid** adding `decoding` or `sizes` props on the component — they trigger Vue hydration attribute mismatches with NuxtImg, which cause duplicate image requests.
 
-### Synthetic srcset fallback
+### CMS Images (`CmsElementImage`)
 
-When Shopware media has no thumbnails (common in Cloud/SaaS setups using CDN-based resizing), the layer generates a synthetic `srcset` using CDN query parameters:
+CMS image elements use `useElementSize()` to measure the rendered container and pass the size to `<NuxtImg>` via `width`/`height` props:
 
-```html
-<img srcset="
-  ...image.jpg?width=400&fit=crop,smart&format=webp&quality=90 400w,
-  ...image.jpg?width=800&fit=crop,smart&format=webp&quality=90 800w,
-  ...image.jpg?width=1200&fit=crop,smart&format=webp&quality=90 1200w,
-  ...image.jpg?width=1600&fit=crop,smart&format=webp&quality=90 1600w"
-  sizes="(max-width: 768px) 100vw, 50vw"
->
-```
+- During SSR, no image is fetched (size is `undefined`)
+- After hydration, the container is measured and a single correctly-sized image is requested
+- The size is multiplied by 2 (for retina) and rounded up to the nearest 100px
+
+### Slider Components
+
+**Slider components** (`CmsElementProductSlider`, `CmsElementCrossSelling`) `inject` the slot count via `cms-block-slot-count` to scale their SSR breakpoints — ensuring media queries account for the container being a fraction of the viewport.
 
-The `format` and `quality` values are taken from the `backgroundImage` config in `app.config.ts`.
+### LCP Image Preloading
 
-> **Note:** Synthetic srcset requires CDN-based image resizing support. See the [Image Optimization](#%EF%B8%8F-image-optimization) section for requirements.
+**`useLcpImagePreload`** scans CMS sections for the first image and injects `<link rel="preload" as="image" fetchpriority="high">` during SSR.
 
 ## 🔄 UnoCSS Runtime
 

packages/cms-base-layer/app/components/SwProductCardImage.vue

@@ -5,9 +5,7 @@ import {
   isProductOnSale,
   isProductTopSeller,
 } from "@shopware/helpers";
-import { useElementSize } from "@vueuse/core";
-import { computed, useTemplateRef } from "vue";
-import { useImagePlaceholder } from "#imports";
+import { computed } from "vue";
 import type { Schemas } from "#shopware";
 
 type Translations = {
@@ -27,49 +25,31 @@ const props = defineProps<{
   productLink: UrlRouteOutput;
 }>();
 
-const containerElement = useTemplateRef<HTMLDivElement>("containerElement");
-const { width, height } = useElementSize(containerElement);
-
-const DEFAULT_THUMBNAIL_SIZE = 10;
-function roundUp(num: number) {
-  return num ? Math.ceil(num / 100) * 100 : DEFAULT_THUMBNAIL_SIZE;
-}
-
 const coverSrcPath = computed(() => {
   return (
-    getSmallestThumbnailUrl(props.product?.cover?.media) ||
-    props.product?.cover?.media?.url
+    props.product?.cover?.media?.url ||
+    getSmallestThumbnailUrl(props.product?.cover?.media)
   );
 });
 
-const imageModifiers = computed(() => {
-  // Use the larger dimension and apply 2x for high-DPI displays
-  // For square containers, width and height should be the same
-  const containerSize = Math.max(width.value || 0, height.value || 0);
-  const size = roundUp(containerSize * 2);
-  return {
-    width: size,
-    height: size,
-  };
-});
-
 const coverAlt = computed(() => {
   return props.product?.cover?.media?.alt || props.product?.translated?.name;
 });
 
 const isOnSale = computed(() => isProductOnSale(props.product));
 const isTopseller = computed(() => isProductTopSeller(props.product));
-
-const placeholderSvg = useImagePlaceholder();
 </script>
 
 <template>
-  <div ref="containerElement" class="self-stretch min-h-[350px] relative flex flex-col justify-start items-start overflow-hidden aspect-square">
+  <div class="self-stretch min-h-[350px] relative flex flex-col justify-start items-start overflow-hidden aspect-square">
     <RouterLink :to="productLink" class="self-stretch h-full relative overflow-hidden">
       <NuxtImg preset="productCard"
         class="w-full h-full absolute top-0 left-0 object-cover"
-        :placeholder="placeholderSvg"
-        :src="coverSrcPath" :alt="coverAlt" :modifiers="imageModifiers" data-testid="product-box-img" />
+        :src="coverSrcPath" :alt="coverAlt"
+        width="400" height="400"
+        densities="1x"
+        loading="lazy"
+        data-testid="product-box-img" />
     </RouterLink>
 
     <div v-if="isTopseller || isOnSale"

packages/cms-base-layer/app/components/public/cms/element/CmsElementImage.vue

@@ -3,15 +3,10 @@ import type {
   CmsElementImage,
   CmsElementManufacturerLogo,
 } from "@shopware/composables";
-import {
-  buildCdnImageUrl,
-  buildUrlPrefix,
-  generateCdnSrcSet,
-} from "@shopware/helpers";
+import { buildUrlPrefix } from "@shopware/helpers";
 import { useElementSize } from "@vueuse/core";
-import { computed, defineAsyncComponent, inject, useTemplateRef } from "vue";
+import { computed, defineAsyncComponent, useTemplateRef } from "vue";
 import { useCmsElementImage, useUrlResolver } from "#imports";
-import { useTypedAppConfig } from "../../../../composables/useTypedAppConfig";
 import { isSpatial } from "../../../../helpers/media/isSpatial";
 
 const props = defineProps<{
@@ -30,34 +25,17 @@ const {
   mimeType,
 } = useCmsElementImage(props.content);
 
-const imageSizes = inject<string>("cms-image-sizes", "100vw");
-const appConfig = useTypedAppConfig();
-
 const imageElement = useTemplateRef<HTMLImageElement>("imageElement");
 const { width, height } = useElementSize(imageElement);
 
-const cdnOptions = computed(() => ({
-  format: appConfig.backgroundImage?.format,
-  quality: appConfig.backgroundImage?.quality,
-}));
-
-const srcSet = computed(
-  () =>
-    imageAttrs.value.srcset ||
-    generateCdnSrcSet(imageAttrs.value.src, undefined, cdnOptions.value),
-);
+function roundUp(num: number) {
+  return Math.ceil(num / 100) * 100;
+}
 
-const srcPath = computed(() => {
-  // Only add dimension params after mount to avoid hydration mismatch
-  // (useElementSize returns 0 during SSR). The srcset handles responsive loading.
-  if (width.value || height.value) {
-    return buildCdnImageUrl(
-      imageAttrs.value.src,
-      { width: width.value, height: height.value },
-      cdnOptions.value,
-    );
-  }
-  return imageAttrs.value.src || "";
+const imageSize = computed(() => {
+  const containerSize = Math.max(width.value || 0, height.value || 0);
+  if (!containerSize) return undefined;
+  return roundUp(containerSize * 2);
 });
 
 const imageComputedContainerAttrs = computed(() => {
@@ -111,7 +89,8 @@ const SwMedia3D = computed(() => {
       ref="imageElement"
       preset="productDetail"
       loading="lazy"
-      :sizes="imageSizes"
+      :width="imageSize"
+      :height="imageSize"
       :class="{
         'w-full': !imageGallery,
         'h-full': !imageGallery && ['cover', 'stretch'].includes(displayMode),
@@ -121,8 +100,7 @@ const SwMedia3D = computed(() => {
         'object-contain': imageGallery || displayMode !== 'cover',
       }"
       :alt="imageAttrs.alt"
-      :src="srcPath"
-      :srcset="srcSet"
+      :src="imageAttrs.src"
     />
   </component>
 </template>