Image Optimization and WebP Delivery with Astro's Image Component

Images can clarify an article, but passing original files directly to img may deliver excessive bytes or shift the layout after loading. The <Image /> component from astro:assets declares build-time conversion and dimensions in the template. For a static blog, the optimized output is fixed during the build rather than delegated to a runtime service.

Import local images

Put transformable images under src/assets and import them as ES modules. Files under public are served unchanged and are not analyzed by Astro’s image pipeline.

---
import { Image } from 'astro:assets';
import cover from '../assets/article-cover.jpg';
---

<Image src={cover} alt="Diagram of the article layout" format="webp" quality={80} loading="lazy" />

A static import lets Astro determine the source dimensions and emit width and height information, reserving space before image bytes arrive. Write concise alt text that conveys the image’s information rather than repeating nearby prose.

format="webp" explicitly generates WebP even from JPEG input, but WebP is not always smallest for transparency, line art, or already optimized images. Choose format and quality by the image’s use and visual result.

Control display size

<Image src={cover} alt="Responsive article card layout" width={960}
  format="webp" class="h-auto w-full rounded-xl" />

With a local import, Astro preserves aspect ratio when one dimension is specified. width: 100% and height: auto let the image shrink to narrow containers; HTML width and height attributes reserve the ratio rather than forcing a fixed CSS size.

For multiple viewport candidates, pair widths with a sizes rule that describes the real layout:

<Image src={cover} alt="Desktop and mobile article screens"
  widths={[480, 768, 960]}
  sizes="(max-width: 48rem) calc(100vw - 2rem), 48rem"
  format="webp" class="h-auto w-full rounded-xl" />

Excessive candidates increase build time and output size. Base the set on the article’s maximum width and representative viewports.

Prevent CLS with dimensions

CLS measures unexpected movement during loading. When image dimensions are unknown, text initially occupies that space and is pushed down later. Local <Image /> imports can emit dimensions automatically. For external URLs, provide known width and height or deliberately use a supported inference feature.

---
import { Image } from 'astro:assets';
---
<Image src="https://images.example.com/diagram.png" alt="API processing flow"
  width={1200} height={675} format="webp" />

External images can change after the build, so rely on a stable CDN and fixed aspect ratio. Avoid cropping technical diagrams with a fixed CSS height and object-fit: cover; that may be acceptable for thumbnails but can remove information from a diagram.

Choose loading priority

Lazy-loading the primary above-the-fold image can delay its appearance. Load that image normally, and reserve lazy loading for images further down the article or list. Do not mark every image high priority, which creates competition.

When Lighthouse reports an image issue, inspect the cause: chosen candidate width, file size relative to display size, emitted dimensions, and above-the-fold loading behavior. WebP alone cannot fix JavaScript or font bottlenecks. A reusable image rule combines source placement, appropriate output widths, reserved dimensions, and position-aware loading.