Data, content, and assets
Use local images
Import source images and let Astro determine dimensions and create optimized output.
8 minute lesson
Images imported from src/ enter Astro’s asset pipeline:
---
import { Image } from "astro:assets"
import workshop from "../assets/workshop.jpg"
---
<Image
src={workshop}
alt="Two developers sketching a data flow on a whiteboard"
widths={[480, 800, 1200]}
sizes="(max-width: 700px) 100vw, 700px"
/>Astro knows the imported image’s dimensions and can generate optimized output. The dimensions reserve layout space before the file loads, reducing visual movement. Responsive widths let the browser choose an appropriately sized file.
Files in public/ follow a different path: reference them with a root URL such as /logo.svg, and Astro copies them without source-image processing. Use public/ when a file must keep an exact name or should bypass transformation. Use a source import when you want build-time validation and optimization.
Alternative text describes the image’s purpose in this context, not its filename. Use alt="" for a decorative image already explained by nearby content. Optimization improves delivery; it does not make the image accessible.
Temporarily rename the imported file and run the build. The failure is useful: source imports turn broken asset references into build errors instead of production 404s.
Lesson completed