# How Astro Handles Image Optimization and Responsive Image Generation: Build-Time Assets Pipeline > Discover how Astro's assets system optimizes images and generates responsive markup at build time using Vite plugins. Learn about srcset attributes and global CSS for better performance. - Repository: [Astro/astro](https://github.com/withastro/astro) - Tags: internals - Published: 2026-03-06 --- **Astro's assets system processes images at build time through a Vite plugin that hashes transformation options, emits optimized files, and automatically generates responsive markup with srcset attributes and global CSS styles.** The **Astro assets system** in the `withastro/astro` repository transforms raw image files into optimized web assets before any JavaScript reaches the browser. This build-time pipeline intercepts image imports, computes deterministic hashes based on transformation parameters, and generates the markup required for responsive images. Understanding this architecture helps developers leverage automatic format conversion, CDN integration, and adaptive image sizing without runtime overhead. ## The Build-Time Image Transformation Pipeline The core orchestration happens in [`packages/astro/src/assets/vite-plugin-assets.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/assets/vite-plugin-assets.ts), where the `vite-plugin-assets` plugin coordinates the entire lifecycle from import detection to final HTML emission. ### Detecting and Filtering Image Imports When you import an image using `import photo from "./photo.jpg"` or reference one in the `` component, Astro detects the request through a Vite filter that matches supported extensions defined in `VALID_INPUT_FORMATS`. The plugin's `load` hook uses an `assetRegex` to intercept these files during the build process. ### Computing Deterministic Asset Hashes To ensure identical transformations reuse the same output file, Astro computes a deterministic hash from the transformation options and the configured image service entry point. The `hashTransform` function in [`utils/hash.ts`](https://github.com/withastro/astro/blob/main/utils/hash.ts) generates this hash, while `propsToFilename` constructs the final filename. This approach guarantees that specific combinations of width, height, format, quality, and layout settings always produce consistent asset URLs. ### Emitting Optimized Files and Metadata The system delegates actual file emission to Vite's `emitFile` API through the `emitClientAsset` function in [`utils/assets.ts`](https://github.com/withastro/astro/blob/main/utils/assets.ts). Simultaneously, `emitImageMetadata` from [`utils/node.ts`](https://github.com/withastro/astro/blob/main/utils/node.ts) stores critical metadata including dimensions, format information, and placeholder SVG data. During development, the plugin creates placeholder URLs via `createPlaceholderURL` and `stringifyPlaceholderURL` in [`utils/url.ts`](https://github.com/withastro/astro/blob/main/utils/url.ts), which contain the assets prefix and base URL. ### Resolving Assets in the Final Bundle In the `renderChunk` phase, the plugin replaces placeholder URLs matching the `__ASTRO_ASSET_IMAGE__` regex pattern with the actual final file paths. The `getAssetsPrefix` utility from [`utils/getAssetsPrefix.ts`](https://github.com/withastro/astro/blob/main/utils/getAssetsPrefix.ts) resolves per-extension CDN prefixes defined in `astro.config.mjs`, allowing different asset types to route to different domains. ## Responsive Image Generation and Layout Modes Astro automatically generates responsive markup when you specify layout modes like `responsive` or `intrinsic`, creating multiple image variants and the corresponding `srcset` attributes. ### Automatic Srcset and Sizes Generation When using `layout="responsive"` with a `widths` array, Astro generates multiple image variants at the specified breakpoints. The logic in [`packages/astro/src/assets/layout.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/assets/layout.ts) computes the appropriate `srcset` values and `sizes` attributes, ensuring browsers download the optimally sized image for the viewport. ### Global Responsive Styles Injection For responsive layouts, Astro injects a virtual CSS module identified by `VIRTUAL_IMAGE_STYLES_ID`. This module loads `generateImageStylesCSS` to provide global responsive-image styles that maintain aspect ratios and prevent layout shift when `settings.config.image.responsiveStyles` is enabled. ## Image Service Integration and Processing The actual image transformation depends on the service entry point configured in `settings.config.image.service.entrypoint`. - **Sharp**: High-performance native resizing implemented in [`services/sharp.ts`](https://github.com/withastro/astro/blob/main/services/sharp.ts) - **Squoosh**: WebAssembly-based processing for environments without native binary support ([`services/squoosh.ts`](https://github.com/withastro/astro/blob/main/services/squoosh.ts)) - **No-op**: Fallback service in [`services/noop.ts`](https://github.com/withastro/astro/blob/main/services/noop.ts) that skips processing but still provides metadata for environments where optimization isn't available During builds, the service generates required variants including different widths and format conversions (WebP, AVIF), returning metadata that feeds into the `srcset` generation. ## Practical Configuration Examples ### Basic Image Optimization ```astro --- // src/pages/index.astro import { Image } from 'astro:assets'; import photo from '../assets/photo.jpg'; --- A beautiful view ``` Astro registers the import, hashes the transformation options (`width=800`, `height=600`), emits `/_astro/photo.8a5c1d.png`, and renders the optimized image tag. ### Responsive Image Layouts ```astro --- // src/pages/gallery.astro import { Image } from 'astro:assets'; import landscape from '../assets/landscape.jpg'; --- Mountain range ``` With `layout="responsive"`, Astro automatically generates a `srcset` containing three variants and injects the necessary CSS via the virtual module system. ### CDN Prefix and Cache Configuration ```javascript // astro.config.mjs export default { build: { assetsPrefix: { jpg: 'https://cdn.example.com/images', png: 'https://cdn.example.com/images', fallback: '/_astro', }, }, adapter: vercel({ client: { assetQueryParams: new URLSearchParams({ v: '20240606' }) } }) }; ``` The `getAssetsPrefix` utility selects the appropriate domain per file type, while adapter-level query parameters append cache-busting strings to every generated URL. ## Summary - The **Astro assets system** operates entirely at build time through [`vite-plugin-assets.ts`](https://github.com/withastro/astro/blob/main/vite-plugin-assets.ts), ensuring zero runtime overhead for image optimization. - **Deterministic hashing** via `hashTransform` guarantees that identical transformation requests reuse cached output files, improving rebuild performance. - **Responsive image generation** automatically produces `srcset` attributes and injects global CSS through the `VIRTUAL_IMAGE_STYLES_ID` virtual module when using responsive layouts. - **Flexible service architecture** supports Sharp, Squoosh, or no-op processing depending on the deployment environment and performance requirements. - **CDN integration** through `getAssetsPrefix` enables per-file-type asset hosting and adapter-specific query parameters for advanced cache control. ## Frequently Asked Questions ### How does Astro determine which image service to use? Astro reads the `settings.config.image.service.entrypoint` configuration to select between Sharp, Squoosh, or the no-op service. Sharp provides high-performance native resizing, Squoosh offers WebAssembly-based processing for restricted environments, and the no-op service acts as a fallback that preserves metadata without transforming files. ### Can I use custom widths for responsive images in Astro? Yes. Pass a `widths` array to the `` component along with `layout="responsive"` or `layout="intrinsic"`. Astro's layout logic in [`packages/astro/src/assets/layout.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/assets/layout.ts) automatically calculates the `srcset` and `sizes` attributes based on your specified breakpoints. ### What happens to image imports during development versus production? During development, Astro generates placeholder URLs containing the assets prefix and metadata via `createPlaceholderURL`, allowing instant feedback without full optimization. In production builds, the `renderChunk` phase replaces these placeholders with final hashed filenames emitted through `emitClientAsset`. ### How does Astro prevent layout shift with responsive images? When `settings.config.image.responsiveStyles` is enabled, Astro injects a virtual CSS module (`VIRTUAL_IMAGE_STYLES_ID`) that includes global styles for responsive images. These styles maintain aspect ratios and prevent cumulative layout shift as images load across different viewports.