From fa037864988e326416c65b7ee9d6e11ec5027742 Mon Sep 17 00:00:00 2001 From: totesforlife Date: Wed, 1 Oct 2025 19:50:34 -0700 Subject: [PATCH 1/2] Add Warning in Docs about Lazy Loading and LCP --- .../src/content/docs/cldimage/basic-usage.mdx | 4 + .../content/docs/cldimage/configuration.mdx | 95 +++++- .../docs/guides/image-optimization.mdx | 23 ++ .../docs/guides/image-performance-lcp.mdx | 279 ++++++++++++++++++ 4 files changed, 400 insertions(+), 1 deletion(-) create mode 100644 docs/src/content/docs/guides/image-performance-lcp.mdx diff --git a/docs/src/content/docs/cldimage/basic-usage.mdx b/docs/src/content/docs/cldimage/basic-usage.mdx index 19c6d06..e79a6f9 100644 --- a/docs/src/content/docs/cldimage/basic-usage.mdx +++ b/docs/src/content/docs/cldimage/basic-usage.mdx @@ -53,6 +53,10 @@ of the image. The `sizes` prop is optional, but recommended for [Responsive Sizing](/guides/responsive-images). +:::tip +For images critical to page load like hero images or other above-the-fold content, consider adding `fetchpriority="high"` and `loading="eager"` to improve your [Largest Contentful Paint (LCP)](/guides/image-performance-lcp). Learn more about [Image Performance & LCP](/guides/image-performance-lcp). +::: + ## Transformations You can further take advantage of Cloudinary features like replacing backgrounds with generative AI and text overlays by adding additional props: diff --git a/docs/src/content/docs/cldimage/configuration.mdx b/docs/src/content/docs/cldimage/configuration.mdx index abc870c..3341e2c 100644 --- a/docs/src/content/docs/cldimage/configuration.mdx +++ b/docs/src/content/docs/cldimage/configuration.mdx @@ -21,6 +21,10 @@ Configuration for CldImage is the same as [getCldImageUrl](/getcldimageurl/confi The basic props required to use CldImage include: +:::tip +CldImage supports all standard HTML image attributes. For performance optimization, see [`fetchpriority`](#fetchpriority) and [`loading`](#loading) below. +::: + -[Learn more about quality](https://cloudinary.com/documentation/transformation_reference#q_quality) on the Cloudinary docs. \ No newline at end of file +[Learn more about quality](https://cloudinary.com/documentation/transformation_reference#q_quality) on the Cloudinary docs. + +## Performance & Loading + +CldImage supports standard HTML image attributes for controlling loading behavior and prioritization. + +
(auto), + example: () => (high), + more: () => (More Info) + }, + { + prop: 'loading', + type: 'string', + default: () => (lazy), + example: () => (eager), + more: () => (More Info) + }, + ]} +/> + +#### `fetchpriority` + +Provides a hint to the browser about the relative priority of fetching the image. + +Use `fetchpriority="high"` for images that are critical to page load, such as hero images or other above-the-fold content that impacts [Largest Contentful Paint (LCP)](/guides/image-performance-lcp). + +**Examples** + +Prioritize a hero image: + + +```jsx +fetchpriority="high" +``` + + +:::caution +Only prioritize one or two critical images per page. Over-using `fetchpriority="high"` can hurt performance. +::: + +[Learn more about fetchPriority](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority) on MDN. + +#### `loading` + +Controls when the browser should load the image. + +By default, CldImage uses `loading="lazy"` to defer loading of off-screen images. For critical images visible on initial page load, use `loading="eager"` in combination with `fetchpriority="high"`. + +**Examples** + +Disable lazy loading for a critical image: + + +```jsx +loading="eager" +fetchpriority="high" +``` + + +[Learn more about loading](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/loading) on MDN. + +:::tip +Learn more about optimizing image performance in the [Image Performance & LCP guide](/guides/image-performance-lcp). +::: \ No newline at end of file diff --git a/docs/src/content/docs/guides/image-optimization.mdx b/docs/src/content/docs/guides/image-optimization.mdx index db4667c..4127298 100644 --- a/docs/src/content/docs/guides/image-optimization.mdx +++ b/docs/src/content/docs/guides/image-optimization.mdx @@ -65,7 +65,30 @@ getCldImageUrl({ +## Prioritizing Critical Images + +For images that are critical to page load (like hero images), you can improve performance by using `fetchpriority="high"` and `loading="eager"` to prioritize their loading and improve Largest Contentful Paint (LCP). + + +```jsx + +``` + + +:::note +Learn more about when and how to prioritize images in the [Image Performance & LCP guide](/guides/image-performance-lcp). +::: + ## Learn More +* [Image Performance & LCP](/guides/image-performance-lcp) * [Responsive Images](/guides/responsive-images) * [CldImage](/cldimage/basic-usage) * [getCldImageUrl](/getcldimageurl/basic-usage) \ No newline at end of file diff --git a/docs/src/content/docs/guides/image-performance-lcp.mdx b/docs/src/content/docs/guides/image-performance-lcp.mdx new file mode 100644 index 0000000..d4d02b5 --- /dev/null +++ b/docs/src/content/docs/guides/image-performance-lcp.mdx @@ -0,0 +1,279 @@ +--- +title: Image Performance & LCP +description: Best practices for optimizing Largest Contentful Paint with prioritized image loading in Astro. +head: + - tag: title + content: Image Performance & LCP - Astro Cloudinary +--- +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +import { CldImage } from '../../../../../astro-cloudinary'; + +import CodeBlock from '../../../components/CodeBlock.astro'; +import HeaderImage from '../../../components/HeaderImage.astro'; + +Largest Contentful Paint (LCP) is one of the Core Web Vitals that measures loading performance. It represents the time it takes for the largest content element visible in the viewport to become visible to the user. + +Since images are often the largest contentful element on a page, optimizing image loading is critical for achieving good LCP scores. + +## When to Prioritize Images + +You should prioritize images that are: + +- **Hero images**: Large, prominent images at the top of the page +- **Above-the-fold content**: Any image visible without scrolling +- **Critical to First Paint**: Images that are essential to the initial page render + +:::caution +Only prioritize images that are truly critical. Over-using priority can actually hurt performance by delaying other important resources. +::: + +## Using fetchpriority with CldImage + +The CldImage component supports all standard HTML image attributes, including `fetchpriority` and `loading`. For critical images, you can set these attributes to prioritize loading: + + + + + + +```jsx +--- +import { CldImage } from 'astro-cloudinary'; +--- + +``` + + +### Understanding the Attributes + +- **`fetchpriority="high"`**: Tells the browser to prioritize fetching this image over other resources +- **`loading="eager"`**: Disables lazy loading, ensuring the image loads immediately + +:::note +By default, CldImage uses `loading="lazy"` for automatic lazy loading. When you set `loading="eager"`, you're explicitly opting out of lazy loading for critical images. +::: + +## When NOT to Prioritize Images + +Avoid using `fetchpriority="high"` for: + +- **Below-the-fold images**: Images not visible on initial page load +- **Decorative images**: Non-critical visual elements +- **Multiple images**: Prioritizing too many images defeats the purpose +- **Images in carousels**: Unless the first image is above-the-fold + + +```jsx +--- +import { CldImage } from 'astro-cloudinary'; +--- + +
+ + /> +
+ + +
+ +
+``` + + +## Best Practices + +### 1. Prioritize Only One or Two Images + +Typically, only your hero image or the largest above-the-fold image should be prioritized. + + +```jsx +--- +import { CldImage } from 'astro-cloudinary'; +--- + +
+ +
+ + +
+ +
+``` + + +### 2. Combine with Responsive Sizing + +Use the `sizes` prop along with priority to ensure the browser loads the appropriate image size: + + +```jsx + +``` + + +[Learn more about Responsive Images](/guides/responsive-images) + +### 3. Optimize Image Dimensions + +Ensure your width and height match the display size to avoid unnecessary data transfer: + + +```jsx + + + + + + height="1200" + alt="" + style="max-width: 800px;" + fetchpriority="high" + loading="eager" +/> +``` + + +### 4. Use Cloudinary Optimizations + +CldImage automatically applies `f_auto` and `q_auto` for optimal format and quality. Keep these optimizations enabled for prioritized images: + + +```jsx + + quality="auto" +/> +``` + + +## Measuring LCP + +To measure LCP and verify your optimizations are working, you can use the Web Vitals JavaScript API: + + +```html + +``` + + +You can also use browser DevTools: +1. Open Chrome DevTools +2. Go to the Performance tab +3. Click the record button and reload the page +4. Look for the LCP marker in the timeline + +:::tip +Google's [PageSpeed Insights](https://pagespeed.web.dev/) and [Lighthouse](https://developers.google.com/web/tools/lighthouse) can also measure LCP and provide specific recommendations. +::: + +## Additional Resources + +- [Largest Contentful Paint (LCP) - web.dev](https://web.dev/articles/lcp) +- [Optimize LCP - web.dev](https://web.dev/articles/optimize-lcp) +- [Measure LCP in JavaScript - web.dev](https://web.dev/articles/lcp#measure-lcp-in-javascript) +- [Core Web Vitals - web.dev](https://web.dev/articles/vitals) + +## Comparison with Next.js + +Next.js provides development warnings when images might impact LCP without the `priority` prop. While Astro Cloudinary doesn't have automatic warnings, you can follow these guidelines: + +**Next.js approach:** +```jsx +// Next.js automatically warns in dev mode + +``` + +**Astro Cloudinary approach:** +```jsx +// Manually apply priority for critical images + +``` + +:::note +In Astro, you need to proactively identify and prioritize critical images. Review your page layouts to determine which images are above-the-fold and visible during initial page load. +::: + +## Learn More +* [Image Optimization](/guides/image-optimization) +* [Responsive Images](/guides/responsive-images) +* [CldImage Configuration](/cldimage/configuration) + From f439c97fcb3b4fbe52a8cf9f74a21ac90f44b722 Mon Sep 17 00:00:00 2001 From: totesforlife Date: Thu, 9 Oct 2025 19:09:20 -0700 Subject: [PATCH 2/2] Addressing comments --- .../content/docs/cldimage/configuration.mdx | 95 +------------------ .../docs/guides/image-performance-lcp.mdx | 44 +-------- 2 files changed, 3 insertions(+), 136 deletions(-) diff --git a/docs/src/content/docs/cldimage/configuration.mdx b/docs/src/content/docs/cldimage/configuration.mdx index 3341e2c..abc870c 100644 --- a/docs/src/content/docs/cldimage/configuration.mdx +++ b/docs/src/content/docs/cldimage/configuration.mdx @@ -21,10 +21,6 @@ Configuration for CldImage is the same as [getCldImageUrl](/getcldimageurl/confi The basic props required to use CldImage include: -:::tip -CldImage supports all standard HTML image attributes. For performance optimization, see [`fetchpriority`](#fetchpriority) and [`loading`](#loading) below. -::: -
-[Learn more about quality](https://cloudinary.com/documentation/transformation_reference#q_quality) on the Cloudinary docs. - -## Performance & Loading - -CldImage supports standard HTML image attributes for controlling loading behavior and prioritization. - -
(auto), - example: () => (high), - more: () => (More Info) - }, - { - prop: 'loading', - type: 'string', - default: () => (lazy), - example: () => (eager), - more: () => (More Info) - }, - ]} -/> - -#### `fetchpriority` - -Provides a hint to the browser about the relative priority of fetching the image. - -Use `fetchpriority="high"` for images that are critical to page load, such as hero images or other above-the-fold content that impacts [Largest Contentful Paint (LCP)](/guides/image-performance-lcp). - -**Examples** - -Prioritize a hero image: - - -```jsx -fetchpriority="high" -``` - - -:::caution -Only prioritize one or two critical images per page. Over-using `fetchpriority="high"` can hurt performance. -::: - -[Learn more about fetchPriority](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority) on MDN. - -#### `loading` - -Controls when the browser should load the image. - -By default, CldImage uses `loading="lazy"` to defer loading of off-screen images. For critical images visible on initial page load, use `loading="eager"` in combination with `fetchpriority="high"`. - -**Examples** - -Disable lazy loading for a critical image: - - -```jsx -loading="eager" -fetchpriority="high" -``` - - -[Learn more about loading](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/loading) on MDN. - -:::tip -Learn more about optimizing image performance in the [Image Performance & LCP guide](/guides/image-performance-lcp). -::: \ No newline at end of file +[Learn more about quality](https://cloudinary.com/documentation/transformation_reference#q_quality) on the Cloudinary docs. \ No newline at end of file diff --git a/docs/src/content/docs/guides/image-performance-lcp.mdx b/docs/src/content/docs/guides/image-performance-lcp.mdx index d4d02b5..3122939 100644 --- a/docs/src/content/docs/guides/image-performance-lcp.mdx +++ b/docs/src/content/docs/guides/image-performance-lcp.mdx @@ -91,7 +91,7 @@ import { CldImage } from 'astro-cloudinary'; width="" height="" alt="" - fetchpriority="high" + fetchpriority="high" /> @@ -184,7 +184,7 @@ Ensure your width and height match the display size to avoid unnecessary data tr + width="1600" height="1200" alt="" style="max-width: 800px;" @@ -194,26 +194,6 @@ Ensure your width and height match the display size to avoid unnecessary data tr ``` -### 4. Use Cloudinary Optimizations - -CldImage automatically applies `f_auto` and `q_auto` for optimal format and quality. Keep these optimizations enabled for prioritized images: - - -```jsx - - quality="auto" -/> -``` - - ## Measuring LCP To measure LCP and verify your optimizations are working, you can use the Web Vitals JavaScript API: @@ -252,26 +232,6 @@ Google's [PageSpeed Insights](https://pagespeed.web.dev/) and [Lighthouse](https - [Measure LCP in JavaScript - web.dev](https://web.dev/articles/lcp#measure-lcp-in-javascript) - [Core Web Vitals - web.dev](https://web.dev/articles/vitals) -## Comparison with Next.js - -Next.js provides development warnings when images might impact LCP without the `priority` prop. While Astro Cloudinary doesn't have automatic warnings, you can follow these guidelines: - -**Next.js approach:** -```jsx -// Next.js automatically warns in dev mode - -``` - -**Astro Cloudinary approach:** -```jsx -// Manually apply priority for critical images - -``` - -:::note -In Astro, you need to proactively identify and prioritize critical images. Review your page layouts to determine which images are above-the-fold and visible during initial page load. -::: - ## Learn More * [Image Optimization](/guides/image-optimization) * [Responsive Images](/guides/responsive-images)