Add optional parameters to the image() schema helper function

[hfournier]

Body

Summary

Optional parameters, like height, width and format, would allow a developer to specify what the generated image should look like as defined in their content collection schema.

Background & Motivation

Using this example:

const blog = defineCollection({
  type: 'content',
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    featuredImage: image(),
    ogImage: image()
  }),
});

we know that blog.featuredImage will give us an ImageMetadata object, that we can use, like <Image src={blog.featuredImage} height="768" with="1024" alt="Featured image"} /> and we get the image we want.

However, suppose the developer wants to use blog.ogImage in a meta tag, like so:

<meta property="og:image" content={blog.ogImage.src} />

which will work, but the developer has no control over the size and format of the generated image. The result will always be the images native dimensions and webp, which is probably not optimal in most cases. For example, facebook accepts only certain MIME types: image/jpeg, image/gif or image/png for og:image.

Goals

Give developers control over images in content collection frontmatter:

• Allow developers to provide height, width and format parameters to the image() helper function
• Generate optimized images that match a specific use case

Example

From the earlier example, we can add either params or an imageOptions param object:

const blog = defineCollection({
  type: 'content',
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    featuredImage: image(),
    ogImage: image({height: 536, width: 1024, format: 'jpg'})
  }),
});

[Princesseuh]

image() is kinda intentionally equivalent to import image from "image.png";, not to getImage or Image.

The way you would process those images would be to pass it to getImage (or Image), like such const processedImage = await getImage({src: post.data.ogImage }). This allow for a lot more freedom since you're able to pass dynamic parameters to the getImage call.

[hfournier]

Thanks Erika, I'm sure I can make getImage() work as you suggested.
But why "intentionally" do it that way? I often see comments in the Astro Lounge from Astro team members (especially @natemoo-re ) about striving to give devs the best DX. Wouldn't what I'm proposing do just that?
So essentially:

• if image() has no params, then it's equivalent to import image from "image.png";
• if image() has params, then it's kinda equivalent to the import plus getImage(), but only returning ImageMetadata

That way, you can define the image you want in your schema, rather than in the code where you're using it, which could be in multiple places (not DRY). I believe that this would result in cleaner code that is more intuitive, and easier to read and maintain. No?

[hfournier]

Aaah, so in .transform() call getImage() passing in desired params, and returning GetImageResult, like this:

ogImage: image().transform(
	async (im: ImageMetadata) =>
		await getImage({ src: im, height: 768, width: 1024, format: "jpg" })
),

<meta property="og:image" content={ogImage.src}>
<meta property="og:image:url" content={ogImage.src}>
<meta property="og:image:type" content={`image/${ogImage.options.format}}>
<meta property="og:image:height" content={ogImage.options.height}>
<meta property="og:image:width" content={ogImage.options.width}>

which I just tried and it worked. Very cool. Thank you.

[Princesseuh]

I'm glad it worked because I honestly wasn't sure, ha. But yes, this is what I would recommend doing, that way you keep the consistent return shape and it's very explicit what result you'll get.

[WhiteHoodHacker]

I am attempting to transform images in the collection config to resize images to a fixed size. I'm following something similar to what is mentioned above.

const profiles = defineCollection({
  type: 'content',
  schema: ({ image }) => z.object({
    name: z.string(),
    profile_image: image().transform(
      async (img: ImageMetadata) => await getImage({
        src: img,
        height: 300,
        width: 300,
      }),
    ),
// ...

This works fine with astro dev. However, when attempting astro build, I get this error after generating optimized images:

ENOENT: no such file or directory, open '<full path to repo>\dist\__ASTRO_ASSET_IMAGE__hpi09QC$__'

I tried installing an earlier version of Astro (4.2.8) to reproduce what @hfournier did, but that did not seem to work. Is this way of transforming images still supported?

[hfournier]

I had only tested in dev.
It appears that the path is incorrect in build.

[hfournier]

FYI - Here's a slightly different transform() That will return ImageMetadata type, same as image() would:

      .transform(async (img) => {
        const alteredImage = await getImage({
          src: img as ImageMetadata,
          height: 300,
          width: 300,
          format: 'jpg',
        });
        return {
          src: alteredImage.src,
          height: alteredImage.options.height,
          width: alteredImage.options.width,
          format: alteredImage.options.format,
        };
      }),

It works in dev. However, it also fails in the build step, so no improvement there.