Image optimization

packages/astro/src/assets/ is Astro's built-in image and SVG pipeline. It exposes the astro:assets virtual module, the <Image> and <Picture> components, and a pluggable image-service interface.

Purpose

Optimize, resize, format-convert, and responsively serve images from local files, content collections, or remote URLs — at build time for static routes and on-demand for SSR.

Key files

File	Purpose
packages/astro/src/assets/index.ts	The astro:assets runtime export (getImage, Image, Picture).
packages/astro/src/assets/internal.ts	Image transform plumbing.
packages/astro/src/assets/runtime.ts	Per-request runtime support.
packages/astro/src/assets/types.ts	ImageMetadata, ImageTransform, ImageInputFormat, etc.
packages/astro/src/assets/layout.ts	The <Image layout=…> modes (responsive, fixed, full-width, none).
packages/astro/src/assets/services/sharp.ts	The default image service: Sharp-backed local image transforms.
packages/astro/src/assets/services/noop.ts	A no-op service for environments that can't run Sharp.
packages/astro/src/assets/services/service.ts	The ImageService interface adapters target.
packages/astro/src/assets/endpoint/	The /_image endpoint that serves on-demand transforms.
packages/astro/src/assets/utils/	URL probing, format detection, dimension inference.
packages/astro/src/assets/svg/	The SVG pipeline and optimizer.
packages/astro/src/assets/fonts/	The font subsystem (see features / fonts).
packages/astro/src/assets/vite-plugin-assets.ts	Vite plugin that resolves astro:assets and processes asset imports.

How it works

graph TD
    A[import.meta.glob src/assets] -->|Vite| B[asset URL + metadata]
    C["<Image src={imported} width=… />"] --> D[getImage transform]
    D --> E{prerender?}
    E -- static build --> F[Sharp transform → emit dist/_astro/...]
    E -- SSR --> G[/_image endpoint]
    G --> H[Service.transform]
    H --> I[Response with optimal format]
    F --> J[<img src=optimized />]
    I --> J
    K["<Image src='https://…' inferSize />"] --> L[remoteProbe → service.transform]
    L --> J

The image service interface is platform-agnostic. Adapters can swap it out (Vercel uses Vercel's image service; Cloudflare uses Cloudflare Images; Netlify uses its image CDN). The default astro:assets service uses Sharp, which is in pnpm's onlyBuiltDependencies allowlist for native compilation.

Components

• <Image src width height alt /> from astro:assets — eager transformation.
• <Picture> for <picture>-style art direction with multiple formats.
• <Image getImage> programmatic — await getImage({...}) returns props you can spread.

feat: disallow getImage on the client (commit 33d6146) made getImage server-only to avoid accidentally shipping the heavy transform path to browsers.

SVG optimizer

feat: svg optimizer (commit 0f7c3c8) added an SVGO-based pipeline at packages/astro/src/assets/svg/. SVG imports return a Vue/React/Astro-friendly component instead of a URL by default.

Sharp encoder configuration

feat: expose Sharp encoder config options for image generation (commit a5e7232) added the image.experimentalEncoderConfig option for fine-grained control over Sharp's output (compression level, chroma subsampling, …).

Remote image policy

astro.config.mjs controls which remote hosts may be transformed via image.domains and image.remotePatterns (uses RemotePattern from @astrojs/internal-helpers/remote).

Related pages

• features / fonts
• packages / integrations / adapters — adapters provide their own image services.
• systems / Vite plugins