Photos go through Astro’s image pipeline, so each one is resized to several widths and served as WebP with a srcset. You add one large file; visitors download only what their screen needs.
Where images go
| Folder | Use it for |
|---|---|
src/assets/images/ |
Photos and other raster images. Optimized at build time |
public/images/ |
SVG logos, icons, and anything that needs a fixed URL |
Don’t put large JPGs in public/. Files there are copied as-is.
Add a photo
- Drop the file into
src/assets/images/. - Export it from
src/assets/images/index.ts:
import studio from "./studio.jpg";
export const photos = {
studio,
// ...
};- Use it in config or on a page:
// src/config/pages.ts
import { photos } from "../assets/images";
about: {
image: photos.studio,
imageAlt: "Our studio on a sunny afternoon",
},Themes with blog post images reference them from each post’s frontmatter instead. Your theme’s page explains where those files go.
Render an image
Use OptimizedImage in your own components:
<OptimizedImage
src={photos.studio}
alt="Our studio on a sunny afternoon"
widths={[480, 768, 1024, 1440]}
sizes="(max-width: 1024px) 100vw, 50vw"
/>It accepts an imported image (optimized) or a string path like /images/logo.svg (passed through untouched).
Add priority to the hero image, or whichever image is the biggest thing on screen when the page loads. It loads right away with high priority; every other image lazy-loads.
Alt text
Every image needs alt. Describe what’s in the picture; use alt="" only for purely decorative images. The build’s SEO check flags images without it.
Demo photos
Themes ship with demo photography so the pages look finished. Replace it before launch. Assets & credits lists the sources and licenses.