diff --git a/docs/storefront/stencil/themes/context/handlebars-reference.mdx b/docs/storefront/stencil/themes/context/handlebars-reference.mdx index fd438dc73..4ad9ff0a1 100644 --- a/docs/storefront/stencil/themes/context/handlebars-reference.mdx +++ b/docs/storefront/stencil/themes/context/handlebars-reference.mdx @@ -810,10 +810,16 @@ Returns language translation keys as a JSON string. - [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/langJson.js) - [See it in Cornerstone](https://github.com/bigcommerce/cornerstone/search?l=HTML&q=langJson) +## Image optimization + +All Stencil image helpers support an optional `lossy` parameter that enables image optimization for better performance. When `lossy=true` is specified, the helper applies lossy compression that results in smaller file sizes and enables automatic WebP conversion for supported browsers. This optimization can significantly improve page load times and reduce bandwidth usage while maintaining acceptable image quality. + +The `lossy` parameter is available for all image helpers including `getContentImage`, `getContentImageSrcset`, `getImageManagerImage`, `getImageManagerImageSrcset`, and `getImageSrcset`. + ### getContentImage ```handlebars showLineNumbers -{{getContentImage path width height}} +{{getContentImage path width height lossy}} ``` Returns a URL for an image uploaded to `/dav/content/`. To learn more about uploading files to your store's server, see [WebDAV](https://support.bigcommerce.com/s/article/File-Access-WebDAV). @@ -823,6 +829,7 @@ Returns a URL for an image uploaded to `/dav/content/`. To learn more about uplo - `path` (String): Image path relative to `/dav/content/`. - `width` (Integer): Width in pixels. - `height` (Integer): Height in pixels. +- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`. #### Example @@ -840,6 +847,13 @@ Returns a URL for an image uploaded to `/dav/content/`. To learn more about uplo {{getContentImage "asset.jpg" width=123}} + + +{{getContentImage "asset.jpg" width=123 height=321 lossy=true}} + + +{{getContentImage "asset.jpg" width=123 lossy=true}} + ``` - [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getContentImage.js) @@ -847,7 +861,7 @@ Returns a URL for an image uploaded to `/dav/content/`. To learn more about uplo ### getContentImageSrcset ```handlebars showLineNumbers -{{getContentImageSrcset path}} +{{getContentImageSrcset path lossy}} ``` Returns a `srcset` for an image uploaded to `/dav/content/`. @@ -855,6 +869,7 @@ Returns a `srcset` for an image uploaded to `/dav/content/`. #### Parameters - `path` (String): Image path relative to `/dav/content/`. +- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`. #### Example @@ -864,6 +879,10 @@ Returns a `srcset` for an image uploaded to `/dav/content/`. {{getContentImageSrcset "folder/asset.jpg" width=123}} + + +{{getContentImageSrcset "asset.jpg" lossy=true}} + ``` - [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getContentImageSrcset.js) @@ -871,7 +890,7 @@ Returns a `srcset` for an image uploaded to `/dav/content/`. ### getImage ```handlebars showLineNumbers -{{getImage stencilImage size}} +{{getImage stencilImage size lossy}} ``` Returns `` tag `src` value for images of a specified size. Values for the size parameter are defined in the `settings` array in [`config.json`](https://github.com/bigcommerce/cornerstone/blob/master/config.json). @@ -881,11 +900,15 @@ Returns `` tag `src` value for images of a specified size. Values for the s - `stencilImage` (String): A Stencil image. - `size` (String): A key in the `theme_settings` object. - `defaultImage` (String): Optional default image URL to use if the `stencilImage` is undefined. +- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`. #### Example ```handlebars showLineNumbers {{getImage image "logo"}} + + +{{getImage image "logo" lossy=true}} ``` - [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getImage.js) @@ -894,7 +917,7 @@ Returns `` tag `src` value for images of a specified size. Values for the s ### getImageManagerImage ```handlebars showLineNumbers -{{getImageManagerImage path width height}} +{{getImageManagerImage path width height lossy}} ``` Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-Image-Manager) image URL for an image uploaded to `/dav/product_images/uploaded_images`. To learn more about uploading files to your store's server, see [WebDAV](https://support.bigcommerce.com/s/article/File-Access-WebDAV). @@ -904,6 +927,7 @@ Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-I - `path` (String): Image path relative to `/dav/product_images/uploaded_images`. - `width` (Integer): Width in pixels. - `height` (Integer): Height in pixels. +- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`. #### Example @@ -922,6 +946,13 @@ Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-I {{getImageManagerImage "folder/asset.jpg" width=123 height=321}} + + +{{getImageManagerImage "asset.jpg" width=123 lossy=true}} + + +{{getImageManagerImage "folder/asset.jpg" width=123 height=321 lossy=true}} + ``` - [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getImageManagerImage.js) @@ -929,7 +960,7 @@ Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-I ### getImageManagerImageSrcset ```handlebars showLineNumbers -{{getImageManagerImageSrcset path}} +{{getImageManagerImageSrcset path lossy}} ``` Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-Image-Manager) image `srcset` for an image uploaded to `/dav/product_images/uploaded_images`. To return an image with a specified image width and height size, we recommend using the `getImageManagerImage` helper. @@ -937,6 +968,7 @@ Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-I #### Parameters - `path` (String): Image path relative to `/dav/product_images/uploaded_images`. +- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`. #### Example @@ -948,6 +980,11 @@ https://cdn.bcapp/3dsf74g/images/stencil/80w/image-manager/asset.jpg 80w, https: {{getImageManagerImageSrcset "folder/asset.jpg"}} + + +{{getImageManagerImageSrcset "asset.jpg" lossy=true}} + ``` - [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getImageManagerImageSrcset.js). @@ -955,7 +992,7 @@ https://cdn.bcapp/3dsf74g/images/stencil/80w/image-manager/folder/asset.jpg 80w, ### getImageSrcset ```handlebars showLineNumbers -{{getImageSrcset stencilImage size}} +{{getImageSrcset stencilImage size lossy}} ``` The `getImageSrcset` helper is a replacement for [`getImage`](#getImage) which allows you to generate either a single image URL (for an `` `src`) or a list of image sizes for `srcset`. Using the [srcset](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-srcset) attribute, you can specify a list of image sizes for the browser to choose from based on the expected size of the image on the page, the device's pixel density, and other factors. @@ -965,6 +1002,7 @@ The `getImageSrcset` helper is a replacement for [`getImage`](#getImage) which a - `stencilImage` (String): A Stencil image. - `size` (String): A key in the `theme_settings` object. - `defaultImage` (String): Optional default image URL to use if the `stencilImage` is undefined. +- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`. You can specify what sizes you want as named arguments on the helper. @@ -977,6 +1015,10 @@ By specifying `use_default_sizes=true` on the helper, a `srcset` string will be ```handlebars showLineNumbers {{getImageSrcset image use_default_sizes=true}} {{getImageSrcset image "https://place-hold.it/500x300" use_default_sizes=true}} + + +{{getImageSrcset image use_default_sizes=true lossy=true}} +{{getImageSrcset image "https://place-hold.it/500x300" use_default_sizes=true lossy=true}} ``` Default sizes: @@ -998,6 +1040,9 @@ Default sizes: {{getImageSrcset image 1x=theme_settings.zoom_size}} {{getImageSrcset image 1x="1280x800"}} {{getImageSrcset image 1x="1280w"}} + + +{{getImageSrcset image 1x="1280w" lossy=true}} ``` By specifying a single size as `1x`, you can choose any image resolution. You can reference a value from the `theme_settings` object (similar to `getImage`), or you can specify your own size inline. `getImageSrcset` does not require `theme_settings` keys to be wrapped in quotes; they should be referenced directly. @@ -1008,6 +1053,9 @@ By specifying a single size as `1x`, you can choose any image resolution. You ca {{getImageSrcset image 1x="1280w" 2x="2560w"}} {{getImageSrcset image 1x="800w" 1.5x="1200w" 2x="1600w"}} {{getImageSrcset image 1x="640x640" 2x="1280x1280"}} + + +{{getImageSrcset image 1x="1280w" 2x="2560w" lossy=true}} ``` By specifying several sizes using the pixel density descriptor, you can generate a `srcset` of different image resolutions for different pixel density screens as described in [Resolution switching: Same size, different resolutions](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#Resolution_switching_Same_size_different_resolutions). For example, you can specify a `2x` image for Retina screens, and a `1x` image for normal screens. @@ -1026,6 +1074,9 @@ As above, you can reference `theme_settings` keys or specify your own size inlin + + + ``` By specifying several sizes using the inherent width descriptor, you can generate a `srcset` of different image resolutions based on width, which can in turn be selected by the browser based on the expected size of the image when the page is painted. It is recommended to use this together with a `sizes` attribute on the `` element as described in [Resolution switching: Different sizes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#Resolution_switching_Different_sizes). In Cornerstone, this is handled automatically via JavaScript. diff --git a/package-lock.json b/package-lock.json index 4e3f8f486..c59d4cfc5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,7 @@ "eslint-plugin-mdx": "^2.0.5" }, "engines": { - "node": ">= 14.0.0" + "node": ">= 18.0.0" } }, "node_modules/@babel/code-frame": {