draft-astro-assets.md

Dynamic Runtime

• Pros: Less boilerplate, just reference the asset right in the template
• Cons: Can't cache ahead of time in SSR, site degrades if api.astro.build goes down
• Cons: no warning/error at build time if asset referenced by name doesn't exist
• Cons: Astro only, asset references wouldn't work client-side in a React component
  • (or degraded, ex: svg would be loaded as a seperate file, couldn't be inlined by the build optimizer)

Icons: import {Icon} from 'astro/components';

• local: <Icon name="book">
  • Loads the SVG in /assets/book.svg
• external: <Icon name="mdi:book" />;
  • Loads the SVG from api.astro.build/icons/..., on demand, then caches until runtime clears memory

Fonts: import {Font} from 'astro/components';

• local: can't use <Font/>, provide your own CSS
• external: <Font name="roboto" />;
  • <Font /> component fetches JSON font data from api.astro.build/fonts/..., on demand, then caches until runtime clears memory
  • <Font /> generates CSS font-family from data, points to woff2 files at /_astro/fonts/...
  • Astro registers /_astro/fonts/* to proxy & cache requests from api.astro.build/fonts/...

Images: import {Image} from 'astro/components';

• local: <Image name="book.png" />;
  • <Image /> generates an img, points src to /_astro/images/?asset="X"
  • Astro registers /_astro/images/* to process, serve & cache the image in /assets/book.png
• external: <Image url='https://...' height=* width=* />
  • <Image /> generates an img, points src to /_astro/images/?url="X"
  • Astro registers /_astro/images/* to proxy, process & cache the ?url source image

Static ESM Imports

• Pros: can fetch and save assets during build, less work to do at runtime in SSR
• Pros: will fail build if asset doesn't exist
• Pros: asset import works across all components (React, Svelte, etc), not just .astro
• Cons: More verbose, boilerplate, unfamiliar to some non-JS developers

Icons: import {Icon} from 'astro/components';

• local: import bookIcon from './book.svg'; + <Icon src={bookIcon}>;
• external: import {book} from 'astro:icons/mdi'; + <Icon src={book}>;
  • Plugin loads the SVG from api.astro.build/icons/..., at build time

Fonts: added via config

v2 (see v1 below): I now am leaning towards fonts being handled differently. Because the browser will only download a font on use, I think it makes more sense to treat fonts as something site-wide configured, and then just used via CSS. Basically, something like https://github.com/feat-agency/vite-plugin-webfont-dl, but built into Astro, like:

// astro.config.js
{
  fonts: ['Roboto', 'Roboto Mono'] 
  // Astro adds the font-family CSS to each page in your build
  // then, just use it by name in CSS
}

Fonts (outdated, see above): import {Font} from 'astro/components';

• local: not posible, provide your own CSS
• external: import robotoFont from 'astro:fonts/roboto'; + <Font src={robotoFont}>;
  • plugin fetches JSON font data from api.astro.build/fonts/..., on demand, then caches
  • plugin generates CSS font-family from data, points to woff2 files at /_astro/fonts/...
  • plugin registers /_astro/fonts/* to proxy & cache requests from api.astro.build/fonts/...

Images: import {Image} from 'astro/components';

• local: import bookImage from './book.png'; + <Image src={bookImage} />;
  • <Image /> generates an img, points src to /_astro/images/?src="X"
  • Astro registers /_astro/images/* to proxy, process & cache the ?src source image
  • Note: need to make sure that book.png is included in the final client build
• external (dynamic): <Image url='https://...' height=* width=* />
  • <Image /> generates an img, points src to /_astro/images/?url="X"
  • Astro registers /_astro/images/* to proxy, process & cache the ?url source image