A generic asset loader helper for content collections

[delucis]

Body

Summary

It would be handy to have an equivalent to the image() helper for content collection schemas that can resolve arbitrary assets from a relative path in frontmatter.

Background & Motivation

Today we’ve made it easy to turn a local image referenced in frontmatter into an image import using our image() helper for content collections schemas. This works well, but users can’t use the same approach for other assets like videos or PDFs, which is not a smooth DX because you need to switch between techniques depending on the type of asset you’re aiming to load.

Goals

• Make it easy to get a Vite import reference for an asset from a local path in frontmatter.
• Support any file type Vite loaders support using an import for.

Example

Similar to image(), use a schema helper to mark a field as needing resolving as an import, something like:

defineCollection({
  schema: ({ asset }) => ({
    pdf: asset(),
  }),
})

Ideally there’d be a way to specify supported file formats?

defineCollection({
  schema: ({ asset }) => ({
    pdf: asset().refine(asset => asset.endsWith('pdf')),
  }),
})

Content could then set the path:

---
pdf: ./menu.pdf
---

And a template could use the resolved URL:

<a download href={entry.data.pdf}>Download PDF Menu</a>

[Princesseuh]

+1. However, I'm concerned by one thing:

In Vite to get the file path of a file, you can simply import them, right. However, this only works for assets that are part of the assetsInclude and small assets get inlined etc. So, to always return an url, we'd need to use ?url, however then we lose compatibility with for instance, if you have a Vite plugin that takes over the import (unless that Vite plugin ignores ?url, but there's no guarantee of that)

So not 100% sure what it'd look like. Maybe it could have a asset({url: true}) flag or something

[delucis]

Yeah, I can see something like that API working to allow people to force a URL import if they need it and could become an important distinction if we add support for importing SVGs as a component. Then there’s a difference between svg: asset() (give me the component to render) and svg: asset({ url: true }) (give me a URL to this SVG in the build).

[delucis]

Noting that this might be solved in Vite 6 which introduces a ?url&no-inline query parameter to tell it never to inline a URL import (added in vitejs/vite#15454).

[delucis]

I don’t know how we could best support file format assertions. The regular Zod approach with refine() works well for image imports because we change the import shape and can read the format data directly. The example in my initial post assumes asset() resolves 1:1 what Vite imports, but that could make it tricky to refine() potentially.

One possibility could be that asset() always returns an object with some properties like:

{
  /** Vite-provided URL to this asset */
  url: string;
  /** File extension or MIME type */
  format: string;
}

Then it’s easier to refine, e.g.

asset().refine(({ format }) => ['mov','mp4'].includes(format))

That does interfere with whatever the import actually returns a bit and could be weird for imports where url is not a string at all…

An alternative would probably be an API inside the asset() helper itself, like

asset({ formats: ['mov', 'mp4'] })

[delucis]

Noting that refine() assertions on image() broke in Astro v5 due to changes in the order things get processed, so what this might look like may need rethinking generally.

AFAIK Astro probably only knows the file extension when parsing with a schema, so only that is probably relevant in terms of refinements.

[luisfos]

I also ran into this issue when embedding videos in markdown. Unlike images, Astro doesn’t process videos — it doesn’t copy them to the build output or update their URLs.

Use case

I manage Obsidian-style content where media (images and videos) live next to the markdown in src/content/**/attachments/*. The body markdown ![]() works for images, but videos in the body or in frontmatter media (e.g., cover) fail on build when they’re not an image.

---
cover: ./attachments/video.mp4
---
2 different ways to embed videos in markdown body.
<video controls preload="metadata" src="attachments/video.mp4"></video>
![works_in_obsidian_but_not_astro](attachments/video.mp4)

Proposal

A generic asset() helper that works like image() but supports any file type, returning { src, ext } and emitting the asset via new URL(). This would allow frontmatter to reference videos or other files while keeping the same co-located content workflow.

For videos in markdown body (and any other generic assets), I’m not sure what the best resolution approach would be — open to ideas on how these could be handled.

Question

This issue has been open for 2 years — was the original proposal accepted in any form, and is there a plan to move it forward?

[delucis]

was the original proposal accepted in any form, and is there a plan to move it forward?

This proposal is as far as it went at the time. This predates some substantial rewrites of the content collection system to support custom content loaders, so was not considered while we worked on those.

To move it forward we’d need to move the proposal to Stage 2 of the RFC process and have buy-in from maintainers. That would require the @withastro/tsc members to accept it and we’d need someone to write up the stage 2 proposal and most likely take on the development work to implement at least a proof of concept.

It’s something I’d personally like to see us do, but there are a couple of reasons it may take a little bit of time:

1. Currently we’re focusing on fixing bugs and stabilising existing Astro features and are slower on the new feature front.

2. Astro v5 introduced some limitations in how the existing image() and reference() helpers work. Improving these is on our radar, but would require some refactors that may not happen until Astro v6. Given that, I don’t know whether it would make more sense to avoid adding a new helper type before then. (I could be wrong though — there’s substantial overlap of the proposed asset() helper and the existing image() one, so we may be able to share code between them that would avoid making the subsequent refactor work much larger.)

[luisfos]

If a refactor is on the cards later, to me it would make sense to extend the current functionality of image() to support generic assets formats like videos. I'm naively assuming that the only difference is non-images can skip the optimisation process.

[aitorllj93]

This would be really great to have it

Also, when talking about big files such as videos, it would be even better if there was some kind of internal (optional) way to serve them using some streaming protocol in server-side platforms