Skip to content

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 ![alt](./x.png) 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)

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:

src/content.config.ts
const posts = defineCollection({
loader: glob({ pattern: "**/*.{md,mdx}", base: "src/content/blog" }),
schema: ({ image }) =>
z.object({
title: z.string(),
cover: image(),
}),
});
src/pages/blog/[...slug].astro
---
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.

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:

src/cms.config.ts
Figure: defineComponent({
props: ({ image }) => z.object({ src: image(), alt: z.string() }),
component: "@/components/Figure.astro",
});
src/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"); // -> ImageMetadata
const 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.

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.

src/cms.config.ts
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.

src/components/Film.astro
---
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.

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.mdx
const img = await resolveImage("../../assets/photo.png", "src/content/blog/post.mdx");
---

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:

src/components/Gallery.astro
---
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} />

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.

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 itself
const 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:

src/content.config.ts
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.

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.

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.

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.

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.