Asset Handling
Every asset reference is handled by whoever owns it. Astro resolves the ones it has a mechanism
for, and the CMS resolves only the one it does not: the props of your MDX components. Nothing is
injected into your Markdown or MDX at build time, so all of it works identically under Astro’s
default satteri() pipeline and under unified().
| Reference | Where | How it is handled |
|---|---|---|
Markdown image  |
prose | Astro’s Markdown processor, no extra wiring |
image() schema field |
frontmatter, data | Astro’s content layer: entry.data.cover is already ImageMetadata |
libraryImage(image) schema field |
frontmatter, data | As above, or the object-store URL as it is |
image() component prop |
MDX component props | Resolved by the generated wrapper, arrives as ImageMetadata |
file() component prop |
MDX component props | Stored as a path string, resolved via astronaut-cms/assets |
file() schema field |
frontmatter, data | Stored as a path string, resolved via astronaut-cms/assets |
Link to a file [doc](/files/x.pdf) |
prose | Put the file in public/ (plain URL) |
Collection fields
Section titled “Collection fields”Declare an image field with the image() helper Astro hands to a schema function. The admin panel
reads it as an image picker, and Astro imports the file for you, so the value you get back is
ImageMetadata and goes straight to astro:assets:
const posts = defineCollection({ loader: glob({ pattern: "**/*.{md,mdx}", base: "src/content/blog" }), schema: ({ image }) => z.object({ title: z.string(), cover: image(), }),});---import { Image } from "astro:assets";const { post } = Astro.props;---
<Image src={post.data.cover} alt={post.data.title} width={1280} height={720} />The media picker writes root-absolute paths (/src/assets/hero.png), which Astro resolves from
your project root; relative paths resolve against the entry file. Nothing in this path goes through
the CMS at render time.
MDX component props
Section titled “MDX component props”A prop of a CMS component is the one reference Astro has no hook for, so the CMS resolves it.
The value is stored as a path string, and the generated wrapper resolves every image() prop before the component renders, nested ones included.
The component receives its images as a collection’s image() field arrives, as ImageMetadata, or as the URL of an object-store file, and ComponentProps types them that way:
Figure: defineComponent({ props: ({ image }) => z.object({ src: image(), alt: z.string() }), component: "@/components/Figure.astro",});---import Image from "astronaut-cms/Image.astro";import type { ComponentProps } from "astronaut-cms:components";
type Props = ComponentProps["Figure"];const { src, alt } = Astro.props;---
<figure> <Image src={src} alt={alt} /></figure><Image> takes an ImageMetadata, an object-store URL or a path string, so the same component renders a block’s prop, a collection field and a manual import alike.
A block is therefore reusable with a collection’s image() value without any conversion.
A file() prop stays a path, as a collection’s file() field does, since only the component knows whether it wants the URL.
For full control, call the resolvers directly:
---import { resolveImage, resolveFile } from "astronaut-cms/assets";const cover = await resolveImage("/src/assets/hero.png"); // -> ImageMetadataconst pdfUrl = await resolveFile("/src/assets/report.pdf"); // -> string URL---The integration generates types for the media backend you configure, so with a repository library resolveImage() is typed as ImageMetadata alone and call sites need no URL branch.
The demo workspace uses exactly this pattern for its Figure and Hero blocks, so it doubles as
an end-to-end example.
Videos and audio
Section titled “Videos and audio”A video or an audio file is a file(): nothing optimizes it, so it is bundled as the file itself and resolveFile() hands back its URL.
A video’s poster is an image(), which is optimized like any other.
Film: defineComponent({ props: ({ image, file }) => z.object({ src: file(), poster: image(), title: z.string() }), component: "@/components/Film.astro",});astronaut-cms/Video.astro resolves both and passes every other attribute on to <video>.
It sizes the element from the optimized poster, which carries the video’s proportions, so the page does not jump when the video loads.
---import Video from "astronaut-cms/Video.astro";import type { ComponentProps } from "astronaut-cms:components";
type Props = ComponentProps["Film"];const { src, poster, title } = Astro.props;---
<Video src={src} poster={poster} posterWidth={1920} aria-label={title} controls muted loop playsinline preload="none" />The poster is encoded as webp unless posterFormat names another format, as with astro’s <Image>.
Audio needs no wrapper: <audio src={await resolveFile(src)} controls />.
A <track> goes inside <Video>, with its .vtt file resolved the same way.
Relative paths
Section titled “Relative paths”Absolute paths are recommended, and the media picker writes them automatically. A relative path is
also accepted when you pass the content file it is relative to as base:
---import { resolveImage } from "astronaut-cms/assets";
// "../../assets/photo.png" written in src/content/blog/post.mdxconst img = await resolveImage("../../assets/photo.png", "src/content/blog/post.mdx");---React islands
Section titled “React islands”React components render synchronously and cannot await, so optimize in an .astro component and pass the URLs down to the island.
A block’s image() props arrive resolved already:
---import { getImage } from "astro:assets";import type { ComponentProps } from "astronaut-cms:components";import Carousel from "@/components/Carousel.tsx";
type Props = ComponentProps["Gallery"];
// A repository image is `ImageMetadata`, an object-store one a URL astro measures itself.const images = await Promise.all( Astro.props.images.map(async (src) => (await getImage(typeof src === "string" ? { src, inferSize: true } : { src })).src, ),);---
<Carousel client:visible images={images} />Assets live in the media directory
Section titled “Assets live in the media directory”CMS asset props are resolved through a map rooted at your media directory, so a path outside it can
never resolve, however real the file is. The CMS enforces this when content is written, by hand or
by the assistant: an image()/file() value must name an existing file in the media library, and
any other path is rejected with the reason. A relative value is resolved against the entry holding
it first — the same way the build and resolveImage(src, base) resolve it — so it is judged by
where it points, not by how it is written. This is what keeps a mistyped or invented asset path
out of your content, where it would otherwise surface as a broken build.
Plain markdown links and public/ URLs are unaffected, since they are ordinary strings and not
asset fields.
Object-store libraries
Section titled “Object-store libraries”Everything above describes the repository library, where astro’s asset pipeline resolves and
bundles the files. With media.s3 configured beside it
(Media Library) the same fields and
props can also name a file in the store, by its public URL:
{ "cover": "https://cdn.example.com/photos/hero.png" }That URL is what astro resolves as a remote image by itself, so every kind of reference in the
table above takes it without any help from the CMS. A markdown image is fetched and optimized by
either markdown processor, and resolveImage() and resolveFile() hand it back unchanged:
---import { resolveImage, resolveFile } from "astronaut-cms/assets";
const cover = await resolveImage("https://cdn.example.com/photos/hero.png"); // the URL itselfconst pdf = await resolveFile("https://cdn.example.com/reports/q3.pdf");---astronaut-cms/Image.astro takes both kinds of value, so one component serves either library:
---import Image from "astronaut-cms/Image.astro";---
<Image src={Astro.props.src} alt={Astro.props.alt} />For a remote image it passes inferSize to astro:assets, which reads the real dimensions from the
image itself, at build time for a prerendered page. Pass an explicit width and height to skip that.
The integration adds your publicUrl to astro’s image.remotePatterns for you, which is what allows
astro to fetch and optimize those images at all. A prerendered page then serves only the optimized
variants, so no visitor downloads an original from the store.
A collection field declared with astro’s plain image() takes repository files only, since astro
types its value as imported ImageMetadata. Wrap it in libraryImage() to take a file from either
library:
import { libraryImage } from "astronaut-cms/config";
const posts = defineCollection({ loader: glob({ pattern: "**/*.{md,mdx}", base: "src/content/blog" }), schema: ({ image }) => z.object({ logo: image(), // repository files only cover: libraryImage(image), // either library }),});A repository file still goes through astro’s own image() and arrives as ImageMetadata, and an
object-store file arrives as its URL, so the field is typed ImageMetadata | string. TypeScript then
refuses to hand it to code that only handles ImageMetadata, and astro’s <Image> asks for a
width and height or inferSize as it does for any remote image. astronaut-cms/Image.astro
takes it as it is. The admin’s picker follows the declaration too: a plain image() field only
offers the repository library, and a URL written into one is refused on save and fails the build.
The CMS reads an object-store URL back as the file it names, so the file counts as used, and delete
and rename warn about it. Changing publicUrl later leaves the stored URLs pointing at the old base,
and the media view lists them as references to missing files.
Nothing of the store is bundled, because nothing of it is in the project: the build emits no copies,
and a build cannot tell you an object-store asset is missing. The check moves earlier instead: the
admin (and the assistant) refuse to write an image() or file() value that is not in the library
it names, which is the same rule, applied when the content is written rather than when it is built.
What a build bundles
Section titled “What a build bundles”Dev and build resolve the same way: every file of the media directory resolves, so a path works whether content, a component or your own code wrote it. A build therefore emits the whole library, and then removes unlinked copies it can identify as library assets.
Once the build is done, the CMS looks at the finished output. It deletes Vite outputs whose recorded sources are library files and which no delivered page, stylesheet, script or data file links. The build log reports the files and bytes removed. Astro image originals without source metadata remain, because their ownership cannot be established safely.
A file that a page does link stays: a resolveFile() download, an image shown with its src, an Open Graph image in a <meta> tag.
Since the decision is taken on the output, it holds however a path got there, a template literal and a path assembled at render time included.
Pages rendered on demand
Section titled “Pages rendered on demand”An on-demand page may link any library file its code reaches at request time, and with imageService: "compile" on Cloudflare it serves such an image as the original.
By default the build keeps the whole library when an on-demand route or server island can reach content or library media.
An on-demand page that does not touch either lets the build prune unused copies.
The CMS routes, Astro actions and the image endpoint do not trigger this rule, since they answer with data or serve what pages already link.
A contact form therefore costs nothing when its page is prerendered and posts to an action, which is the pattern to prefer.
An on-demand page importing a logo keeps the whole library by default.
An on-demand page reading a collection does too.
Set media.repo.prune to true if your on-demand code reaches media but never renders library files, or to false if it constructs library URLs at request time without importing the files.
Every image() or file() value your content declares is checked when you build: a repository path the media directory does not hold fails the build, naming the entry and the field or prop it came from, rather than turning into a broken image at render time.
Files your own code uses
Section titled “Files your own code uses”A path written in site code rather than in an entry, the default Open Graph image of a layout say, needs no configuration:
---const og = await resolveImage("/src/assets/og-default.png");---The build keeps it because the page links it, as for any other file. The admin only knows the references your content holds, so it does not warn before deleting or renaming a file only site code uses. Such a deletion fails the next build of a prerendered page, or the request of an on-demand one, naming the missing file.
The media library lists files through the storage backend, not through the bundle, so every upload stays visible and pickable in the admin panel whether or not anything references it yet.
Downloadable files
Section titled “Downloadable files”A file editors manage (a PDF, an archive) belongs in the media library, declared with file() and resolved with resolveFile(), which content-hashes it, and a build keeps it wherever a page links it.
A file only site code links to can equally sit in public/ and be referenced by URL (e.g. /files/report.pdf), served verbatim with no bundling step.
