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/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..3122939 --- /dev/null +++ b/docs/src/content/docs/guides/image-performance-lcp.mdx @@ -0,0 +1,239 @@ +--- +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 + + + + + +``` + + +## 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) + +## Learn More +* [Image Optimization](/guides/image-optimization) +* [Responsive Images](/guides/responsive-images) +* [CldImage Configuration](/cldimage/configuration) +