Local images and assets
Small, honest notes on bundling images and static files with Astro.
Two asset pipelines coexist in Astro: public/ and imported assets.
public/ — copies, no processing
Anything in public/ lands in dist/ untouched, at the same relative path:
public/favicon.svg -> dist/favicon.svg
Reference it with a root-absolute URL: href="/favicon.svg".
src/assets — bundled and fingerprinted
Import an image in your page frontmatter and it flows through the bundler:
import hero from '../assets/hero.svg';
<img src={hero.src} alt="Hero illustration" width={hero.width} height={hero.height} />
The emitted file gets a content hash in its name, so browsers can cache it aggressively. This is the route this site uses for its hero art.
The full-service path: astro:assets
For production-heavy sites, use the Image component:
---
import { Image } from 'astro:assets';
import hero from '../assets/hero.svg';
---
<Image src={hero} alt="Hero illustration" />
You get width/height attributes, format negotiation, and (with a sharp backend) responsive resizing. Small sites often do not need it — but it is there when images get heavy.
Practical rules
- Keep
public/for favicons, robots.txt, static manifests. - Import anything you want hashed or transformed.
- Always set descriptive
alttext — accessibility is part of quality. - SVG you draw by hand (like this site’s logo) is compact and theme-friendly.