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'] })