A plan for a core image story

[Princesseuh]

Body

Summary

This proposal aims to outline a plan for a core story for images in Astro, doing so by:

• Making the image component easier to use through reducing the amount of necessary props in most cases, more intuitive properties, behaviour that is closer to similar tools in the ecosystem and an overall enhanced developer experience (better error messages, better types etc)
• Adding a new path to import images assets from in a consistent way (inspired by the current src/content)
• Make things nice and easy to use both in Astro files and in Markdown
• All of it in core, no more integration to install!

Background & Motivation

src/assets folder

Using images in Astro is currently a bit confusing. Should my images go in public or src? How do I refer to them?

For this, we'd like to introduce a src/assets folder. This folder would be used for your source assets, as in, your not optimized, raw assets. Usage of this folder would be recommended, but not forced.

To make it easier to use this folder from anywhere in the project, an alias will be provided so it is possible to write ~/assets. Due to necessitating tsconfig.json changes, this will only affect new projects, and is completely optional.

Content Collection integration

It is fairly common for one of the property of a Markdown piece of content to need to be a reference to an asset (think, cover image for an article, picture for an author etc).

In tandem with the src/assets folder, we'd like to introduce a way for users to specify that a specific property needs to refer to a valid asset from the src/assets folder. This would allow us to provide validation of the asset, think cover needs to be a png of size 240x240, including validating that the file actually exists.

Facts

• ESM importing images from other folders than src/assets is supported and they would be optimized, like before.
• In Markdown, referring relatively to assets from other folders than src/assets is also supported (ex: ![...](./image.png)) in addition to the src/assets folder (ex: ![...](~/assets/image.png))
• Images in the public folder can still be referred to, however, they won't be optimized / transformed. We would like for this folder to be kept for its original purpose, for assets that will be copied as-is.
• Content collection-powered validation only works for assets inside the src/assets folder. Remote images are currently out of scope and still need to be referred to using a z.string.
• TL;DR:
  • In Astro files, refer to local assets by ESM import anywhere in src and they'll be optimized.
  • In Markdown, use the ![] syntax and refer to images in src/assets or relative to the file and they'll be optimized.
  • Need an asset in the frontmatter and want to valid it through content collection? Refer to one from src/assets.

Image component

(see #447 for an earlier version of this proposal)

The current Image component can be confusing to use at time. Why do I need to set an aspectRatio? (what even is the aspect ratio of my image?) Why is my image getting cropped? What format should I use? What does quality means?

width, height and aspectRatio

We'd like to make it so less properties are needed in general. In most cases, the width and height would be automatically inferred from the source file and not passing them would just result in the same dimensions, but a smaller weight.

For cases where they're needed, we'd like to remove the aspectRatio property, instead preferring that users manually set both width and height. Combined with [[#Better behaviour for resizing images]], we believe that this will lead to a more consistant and easier to resonate about experience.

format

format would be set to webp by default, removing the need for it to be passed completely. We believe WebP to be a sensible default for most images, providing with a smaller file size while not sacrificing on compatibility and support for transparency.

quality

For quality, we'd like to make it easier for people to use without needing to know the in-and-out of the loader's algorithm for quality. We propose to fix this by introducing different presets that users can choose from, for example: quality: 'low' would automatically set an appropriate, approximative quality that is considered 'low' (specific implementation is left to the loaders to decide.)

Better behaviour for resizing images

Despite the tremendous power it offered, users were often confused by how @astrojs/image would crop their images to fit the desired aspect ratio. This was especially confusing for users coming from other popular frameworks that don't offer this feature.

As such, this feature would be removed of the base toolkit. Resizing would now only operate in ways that follow the original image aspect ratio (based on width). To control how an image is fitted inside its container, the object-fit and object-position CSS properties can be used.

For users used to other frameworks, this is a similar behaviour to the one offered by NextJS's next/image and Eleventy's eleventy-img.

Facts

• For ESM images, the only required property would be src. Remote images (ex: http://example.com/image.png, /image.png or ${import.meta.env.BASE_URL}/image.png) would however require width and height to be set manually.
• Remote images would not be optimized or resized. We understand the need for this, but would like to orient our users towards self-hosing their images as much as much as possible, at least for now.
• src can be a dynamic import, but be aware that it must respect Vite's limitations on dynamic imports
• format would be set to webp by default, with the possibility to override as needed. If you desire to have the same format as the original, for remote images it needs to be manually provided whereas for local images, it is possible to do format={myImage.format}.
• quality now accepts two types of values, either a preset (low | mid | high | max) or a specific number (0 - 100).
• alt is a required property in all cases. It can be explicitly set to "", for cases where an alt-text is not required.
• By default, images are loading="lazy" and decoding="async", with possibility to override as needed.
• TL;DR: The complete list of property would be src, width, height, quality, and all the properties natively available on the img tag (alt, loading, decoding, style etc)

Shape of ESM imports

Currently, importing images in Astro returns a simple string with the path of the image. The @astrojs/image integration enhance this by instead returning the following shape: {src: string, width: number, height: number, format: string}, allowing users to easily construct img tags with no CLS:

---
import image from "../my_image.png"
---

<img src={image.src} width={image.width} height={image.height} />

This shape should also give most of the information an user could need to build their own image integrations based on ESM imports.

Since this would be directly in core, there would be no more configuration changes needed to get the proper types and as such, editor integration should be painless (completions, type checking etc) and address user confusion around this.

In order to avoid any breakage, this shape would be under an experimental flag until the next major release of Astro. Similarly to content collections, we would automatically update your env.d.ts with the type changes needed for this.

Goals

• A consistant, robust and friendly way to include images into your page
  • No CLS.
  • Enforced best practices (alt, loading, decoding)
  • Optimized images with good defaults, but still flexible
• With the all the usual good DX you expect from Astro (good error messages, good types etc)

Non-goals of this proposal

• Advanced usage in Markdown (ability to set width, height, quality etc)
• Using optimized images inside framework components
• Automatic generation of srcset
• Placeholders generation
• Background generation
• Picture component
• Optimizing remote images
• .svg support

We realize that many of those features not being goals are considered to be downgrades compared to @astrojs/image. This is on purpose as we'd like to approach this project with a "small MVP, add features over time" mentality.

Creating a perfect Image component for core is a way more complex project than it might seems, the balance between "This has too much options, it's too confusing to use" and "This doesn't have enough options, it's unusable for anything even a little bit complex" is incredibly hard to hit.

We believe that, much like we did with other features in Astro, by building a good core and providing ways build around it, we'll ultimately achieve the best result possible.

Example

All the examples below show the result path in the built website

Basic image from src/assets

Source

---
import { Image } from "astro:image";
import myImage from "~/assets/my_image.png"; // Image is 1600x900

// Relative paths are also supported:
// import myImage from "../../assets/my_image.png"
---

<Image src={myImage} alt="Image showing Elsa from the movie Frozen, she has blonde hair and is wearing a long blue dress" />

Result

<img src="/_astro/my_image.hash.webp" width="1600" height="900" decoding="async" loading="lazy" alt="Image showing Elsa from the movie Frozen, she has blonde hair and is wearing a long blue dress" />

Resized image from src/assets

Source

---
import { Image } from "astro:image";
import myImage from "~/assets/my_image.png"; // Image is 1600x900
---

<Image src={myImage} width={800} alt="..." />

Result

<!-- Result image is a webp of 800x450 -->
<img src="..." width="800" height="450" decoding="async" loading="lazy" alt="..." />

Source

---
import { Image } from "astro:image";
import myImage from "~/assets/my_image.png"; // Image is 1600x900
---

<Image src={myImage} width={800} height={900} alt="..." />

Result

<!-- Result image is a webp of 800x450 -->
<img src="..." width="800" height="900" decoding="async" loading="lazy" alt="..." />

Basic remote image

Source

---
import { Image } from "astro:image";
// Image is 1920x1080
---

<Image src="https://example.com/image.png" alt="..." />
<!-- ERROR! `width` and `height` are required -->

<Image src="https://example.com/image.png" width={1280} alt="..." />
<!-- ERROR! `height` is required -->

<Image src="https://example.com/image.png" width={1280} height={720} alt="..." />

Result (3rd example)

<!-- Remote images are not optimized or resized.
<img src="https://example.com/image.png" decoding="async" loading="lazy" width="1280" height="720" alt="...">

Markdown

Source

Source image is a .png of 640x960

---
cover: ~/assets/cover.png 
---

Result

Result is a .webp of 640x960

{
    cover: {
        src: "/_astro/cover.hash.webp",
        width: 640,
        height: 960
    }
}

Source

My super image of 640x480:
![...](~/assets/my_image.png)

OR

![...](./my_image.png)

OR

![...](../../assets/my_image.png)

Result

<img src="/_astro/my_image.hash.webp" width="640" height="480" loading="lazy" decoding="async" alt="...">

[FredKSchott]

Thanks for the proposal @Princesseuh! I appreciate your willingness to make good tradeoffs here, historically images have always been one of those controversial topics where everyone has different, sometimes competing goals. This seems well thought-out in the face of so much uncertainty!

Also: Markdown Frontmatter Images ftw!

I'll give this a deeper read later today.

Disclosure: I helped give feedback on earlier drafts of this.

[FredKSchott]

Just circling back to say +1 on this proposal. Looking forward to seeing an accepted proposal so that this dream can become a reality!

One (not-blocking) comment on the non-goal "Using optimized images inside framework components" -- I would still love to see this as a future goal, to be explored after and outside of this proposal.

[jasikpark]

This looks really solid! Good exploration of tradeoffs and goals.. I wish there was support for mixing of MD/MDX and assets like in Hugo Page Bundles.. it makes for a nice authoring experience to be able to throw one-off blog post assets in the same folder as their referring content.

That might be a non-goal here / in astro:content though 😓 idk

[jasikpark]

ex

gets used via

{{< figure >}}
{{< img src="IMG_4053" alt="cool people enjoying nature" title="cool people enjoying nature" >}}
{{% figcaption %}}
The native trees in the canyons are juniper cedar cypress trees, which look vaguely like christmas trees! They have a wonderful scent that fills the windy brisk air as we hiked.
{{% /figcaption %}}
{{< /figure >}}

which is a Hugo shortcode based on https://laurakalbag.com/processing-responsive-images-with-hugo/

[Princesseuh]

It's more of a astro:content thing ultimately for src/content, but supporting relative images in Markdown is part of this proposal!

[jasikpark]

Right, I guess the two parts of my comment are 1. yes, please relative images in Markdown, but also 2. colocated images next to the Markdown on the filesystem

[kasvith]

I vote for colocating images for markdown

This is the biggest reason we wont use Astro for content authoring

[natemoo-re]

One thing that I don't see mentioned here is how we'll handle the native img tag since we're changing the shape of image asset imports. Any thoughts on that? My thinking is that we might be able to accept both string and { src: string } for the src attribute?

[matthewp]

I wasn't thinking that using it explodes to provide the width and height, just that we accept this object in the templates the same way that we accept a Promise. We unwrap the object to get the underlying src. The "explode" idea is pretty cool though... but agree that it goes against the modifying HTML thing. I was thinking of it more as a workaround for this being a breaking change, but since it is not then it's not needed.

[matthewp]

Actually, thinking about this again, if this is behind a flag that means it has to stay behind a flag until 3.0. That could be 6 months away, or more. I would imagine we don't want this new feature to be experimental for that long. So we'll probably want some solution for this, probably a config option of some sort.

[FredKSchott]

Aren't experimental flags just short-term, short-lived config options? Not sure I understand the difference.

Also, some feedback we got from 2.0 was that it would have been beneficial to have a longer, public experimental phase, so ~5mo behind a flag (and/or shortening the window to 3.0 by an additional 1-2mo) wouldn't be the end of the world for me, personally.

[matthewp]

The difference is that the experiment flags can break (and have often in the past). I don't think I'd be comfortable using an experimental feature for 5 months personally. Having a real config option is also good for the deprecation strategy of:

1. Opt-in during 2.x
2. Opt-out in 3.x
3. Old way completely removed in 4.0

Which is the strategy we've followed on deprecated features in the past, for ex. legacyFlavoredMarkdown and Astro.resolve.

[matthewp]

We could be sneaky and do something like this to remain backwards compat:

class ImageResource extends String {
	constructor(url, width, height) {
		super(url);
		this.url = url;
		this.width = width;
		this.height = height;
	}
}

let r = new ImageResource('/images/penguin.png', '300px', '200px');

console.log(r.slice(0)); // -> /images/penguin.png

const { url, width, height } = r;
console.log(url, width, height); // -> /images/penguin.png 300px 200px

[wassfila]

@Princesseuh I'm wondering if this RFC can discard the need for "Support Markdown images relative path" #376 given that #381 is also closed, it feels like simple relative path (server runtime dynamic not import static) overall support (.astro, .md, .js) is being ignored (which is what the community plugins and integrations have achieved).

RFCs Comparision

• Ambitions of relaive paths RFC do not necessarily include an optimization step, which could be likely a source of unnecessary troubles for those who do not need it.
• The overlap and common goal with this RFC is the assets management and copy in _astro
• The relative path RFC does include svg support which is namely excluded here, that might make it irrelevant for all those who use svg, Today, who doesn't.

Questions

• hash generation is fair to save directories count and parsing,... I'm just afraid if it is a real hash that stays the same if the file does not change, or if it crashes caches concepts on every new generation ?
• would it be possible to disable optimizations and keep bit-identical source images, just managed and deployed ?
• would it be possible to take advantage of asset management for any file type, with e.g. getManagdURL() function ?

[Princesseuh]

We (or at least I) consider the relative images in Markdown to actually be a key part of this RFC, as one of the underlying goal is to provide a way to use optimized images in Astro and Markdown files (MDX can use the same procedure as Astro files)

The underlying logic supporting the ability to import images from ~/assets is pretty much the same supporting relative images, so at least from a technical sense, it makes sense for us to couple those together.

This RFC also aims to cover all the modes in which Astro runs, whereas the popular community integration and suggestions for this tend to not support SSR (there's a very important technical reason for references needing to be statically analysable, unfortunately)

---

• hash generation is fair to save directories count and parsing,... I'm just afraid if it is a real hash that stays the same if the file does not change, or if it crashes caches concepts on every new generation ?

The hash would be generated based on the image generated, as such allowing for permanent, immutable caching. Changing the parameters used to build the image, or the image itself will change the hash.

• would it be possible to disable optimizations and keep bit-identical source images, just managed and deployed ?

In Markdown, we're currently aiming for this to be behind a feature flag, as it is a breaking change.

• would it be possible to take advantage of asset management for any file type, with e.g. getManagdURL() function ?

Currently this proposal is scoped to images. Support for other formats would have to be defined in separate proposals, however I imagine this to be technically possible

Thank you for your feedback!

[kasvith]

As we have discussed in #376 and #334

All we want is to keep related content together.

Apart from Typesafety, I don't see a benefit with the new src/contents architecture without this.
For content authors, it's crucial to keep related assets together. All major content authoring tools like Hugo, Gridsome, and Gatsby supported this from the early days.

So I agree with what @wassfila is adding here. Start simply by supporting relative assets to MD/MDX.
Then on top of it add others gradually.

[kasvith]

Related assets should be the Primary goal, if Astro needs to be a platform for content(because every single one of them supports this out of the box, but astro)

[matthewp]

Does WordPress support this out of the box? My memory of using WordPress is that you upload assets separately from your content, and then reference them in your content.

[kasvith]

@matthewp WordPress is a totally different story. it's like comparing apples to oranges. WordPress is a CMS so it handles everything.

It would be best if you compared it with the other competitors of Astro, possibly every one of them including Hugo, Gridsome, and Gatsby supports this trivial thing.

[matthewp]

@kasvith Our aspiration is to compete with WordPress. We don't want to be just a SSG forever.

[kasvith]

So Astro will become a CMS? like WordPress with a DB?

[andrezero]

Great stuff, but it misses the most important requirement for me: co-located images and "natural" imports":

• keep my images next to my content
• and use relative paths for my images
• which allows ANY editor to auto-complete the paths as you type
• and allows the editor to preview raw content with images (before you build)

Basically ☝️ this is the basic MD experience. We shouldn't have to give up on any of these because of framework opinions or constraints.

EDITED: supporting relative images in Markdown is part of this proposal! I misread it. (mostly because I had some particular - probably unreasonable - expectations about the potential of Astro for certain use cases)

Speaking of which, I am curious:

❓ Why is Astro opinionated about where the images should be stored? Is it because of some technical constraint? Or do you believe it somehow improves the authoring and content management experience?

Note 1: I was able to rollout relative paths without much fuss, together with a bunch of other requirements inherited from the previous version of my website. I wouldn't have migrated to Astro if I didn't believe these were possible to achieve with built-ins and/or extending it 🥺 Please don't break it! 😅

Note 2: Regarding "no CLS" requirements, setting width and height explicitly only works where images are styled to absolute pixel dimensions. When dimensions are responsive and/or fluid - as far as I know - it that can only be achieved by using the padding top percentage technique.

[Princesseuh]

Hi, relative images are part of this proposal. To quote the proposal:

In Markdown, use the ![] syntax and refer to images in src/assets or relative to the file and they'll be optimized.

Sorry if this was unclear. The workflow you described would be supported, both for SSG and SSR websites.

❓ Why is Astro opinionated about where the images should be stored? Is it because of some technical constraint? Or do you believe it somehow improves the authoring and content management experience?

Similar to how Content Collections enhance the two later points and allow for other platforms to more easily build on top of Astro's content story, yes the src/assets is intended for this. Nonetheless, we're not opinionated on where your images and other assets are, as long as they can be referred to according to Vite's rules and we can know to add them to your website in both SSG and SSR, it's fine by us!

Note 1: I was able to rollout relative paths without much fuss, together with a bunch of other requirements inherited from the previous version of my website. I wouldn't have migrated to Astro if I didn't believe these were possible to achieve with built-ins and/or extending it 🥺 Please don't break it! 😅

No worries, not planning on breaking it! If this workflow works perfectly for you, we'd even recommend that you keep it over the official solution. Personally, I built and used astro-eleventy-img despite the official Image integration (@astrojs/image) existing because I didn't like how it worked. We're happy that users are able to build better workflows for their needs when needed.

The goal of this proposal and integration in core is to have a "Good enough solution for the average Astro user", some people are writing their Markdown files directly, some people uses CMS (which love having a stable assets folder!), some people are using MDX, some people are in SSG or some people are in SSR (sometimes with Node, sometimes without), it's a lot of things we need to support and that comes with careful considerations to make, unfortunately.

It won't answer every need, and that's okay. Much like our default Markdown setup does not answer certain needs better covered by Remark plugins, we want to build something you can build on top, or not, that's ok too.

Note 2: Regarding "no CLS" requirements, setting width and height explicitly only works where images are styled to absolute pixel dimensions. When dimensions are responsive and/or fluid - as far as I know - it that can only be achieved by using the padding top percentage technique.

Nowadays you can use a technique called art direction for this on picture: https://web.dev/patterns/web-vitals-patterns/images/responsive-images/ (every source can have its own width and height), though it's very modern and I believe Firefox doesn't support it super well yet

[andrezero]

The workflow you described would be supported, both for SSG and SSR websites.

Awesome, sorry I misread it.

And thanks for replying

Nowadays you can use a technique called art direction for this on picture

Not sure I understand. The article you linked is not concerned with CLS. It's clear how to use <picture>, <source> and/or <srcset> for densities, resolutions, and supported format (actually pretty well supported in Firefox), but not for CLS, especially with fluid layouts. But don't worry, this is definitely not the forum for this!

[Princesseuh]

Not sure I understand. The article you linked is not concerned with CLS

Since every source can have its own width and height, you can set it differently depending on the aspect ratio of the specific image you're serving at the resolution you're serving. Like such:

<picture>
  <source media="(max-width: 799px)" srcset="puppy-480w-cropped.jpg" width=480 height=400/>
  <source media="(min-width: 800px)" srcset="puppy-800w.jpg" width=800 height=400/>
  <img src="puppy-800w.jpg" alt="Puppy with balloons" width=800 height=400/>
</picture>

This is something Firefox dragged a bit with, as you can see here: https://caniuse.com/mdn-html_elements_source_width

You can read more about this on this page from web.dev: https://web.dev/optimize-cls/ (the snippet higher up is taken from that article)

[andrezero]

Yes for both. 🤣 Full circle here.

~Setting width and height explicitly only works where images are styled to absolute pixel dimensions. ~

From my original post suggestion that "padding top percentage technique" is needed in those cases

[...]

Please take this into consideration, and beware of "eliminate 100% CLS" claims.

Edited ☝️ @Princesseuh you are absolutely right: setting width and height on the <img> element is enough as the browsers are now able to infer aspect-ratio and then honour it even when styling the image with width: 100%; height: auto

Thank you very much for showing me the light and sorry for polluting this thread with a non-issue.

[gotofritz]

[Princesseuh]

Thank you for your feedback, I'll add a mention of it a bit earlier in the proposal so it's harder to miss! I was hoping that it being one of the examples would help clear this.

[andrezero]

now that you say that, I forgot the un-down-vote ... I had also down-voted for the same reason

[FredKSchott]

I'm happy that this proposal solves the colocation problem that you all are having, but please refrain from down-voting proposals without actually reading them.

Erika's done a great job here of balancing several difficult tradeoffs that the rest of our team hadn't been able to resolve. Images are hard, especially to crack support in both SSG & SSR. There's a good reason other projects (Remix, SvelteKit) don't even have an official image component!

Feedback is always be encouraged, but please keep it constructive. A few quick tips for reviewers:

• Assume the best: Everyone here is trying to make Astro better.
• Ask questions: If you don't see something, just ask! "I don't see X listed as a goal, is there a reason why?" is a much more constructive comment than "This doesn't do X." Nate and Matthew are both great at this, if you read their comments above.
• See the big picture: Authors are attempting to juggle and communicate on multiple different goals/non-goals/trade-offs, not just the one thing we care about as individual reviewers. See and appreciate the whole picture for what it is.

Thanks for taking the time to read!

[andrezero]

Looks like the OP has deleted the comment so I am not sure how non-constructive it was. But somehow, I feel I can relate. I confess I also felt a bit 😳 ashamed myself, sort of wrist slapped in a way.

Don't worry, I am not going to haunt your project with negativity, when I feel embarrassed I tend to hide in a shell, and never come back. But instead of the usual hey there👋 sorry, didn't mean to misstep, was just trying to help I want to leave a couple of thoughts.

Some of the people that flocked here were concerned with the "relative paths" or "co-located" use cases. Arguably some people that love ❤️ Astro and somehow created an expectation of seeing some MD content management use case(s) addressed by the core team.

Let me clarify that when I think of MD content management use cases I also see a big picture. A whole universe of MD files first use cases. It's not just my personal website, it's technical docs, API specs, decision records, style-guides, libraries, syllabuses, runbooks, checklists, design systems, etc... for the best part of the last 10 years, I've been savouring the MD fruits of this tree that has been growing since the first wiki was planted.

I am going to continue watching the project and even rooting for the compete with Wordpress CMS vision - yes, it's not hard to imagine all of that, and I am sure y'all are going to 🤘 rock it.

Meanwhile, it is also not hard to image an architecture for Astro that would allow it to continue exposing the less opinionated core (basically Astro 1.x) with the vite wrapper, the dev server, the server/static mix-and-match modes, the integration/plugin architecture, the <Astro> component system, ... (I am sure I am missing something)

On top of that it is also not hard to image incremental builds, on-demand, event driven, lambdas or edge functions.

And it's still not to hard to image the most awesome CMS on top of this. With a vibrant ecosystem of integrations, plugins, and themes. And a healthy, robust business capitalising in a few different ways.

Just 🥗 food for thought 💭, an attempt to look at the another big picture, shed some light on (other) trade-offs and eventual blind spots.

Hope it helps. Keep rocking!

tl;dr: hey there👋 sorry, didn't mean to misstep, was just trying to help

[matthewp]

We like to release early and often in Astro. Some projects are conservative and stay in beta for months or years until everything is perfect. That's not us. We prefer to get an idea out to users to see if they even care.

We know content collections is imperfect. We know some use cases aren't covered. But we also think it's a good start and an improvement over previous Astro.glob workflows. So we think it provides benefit to users today and we can use the feedback to improve it. And were absolutely taking that feedback. So thank you for giving yours.

But also, this is a proposal for images. It's not the final solution for everything. So let's keep this discussion focused on this proposal.

[MoustaphaDev]

One question that I have is regarding the specification of the width and height props when using remote images. Why do we need to specify these props if the images don't get resized?
I'm just curious to understand the reasoning behind this requirement.

[Princesseuh]

One question that I have is regarding the specification of the width and height props when using remote images. Why do we need to specify these props if the images don't get resized?
I'm just curious to understand the reasoning behind this requirement.

To still benefit from the Image component guarantees regarding CLS (so it results in <img src="..." width="..." height="..." />)

[MoustaphaDev]

Yeah understood that, I was asking more because in the 3rd example, the values of width and height don't seem to have any effect

In the example, it's said that the

Image is 1920x1080

But then this

<Image src="https://example.com/image.png" width={1280} height={720} alt="..." />

Results in

<img src="https://example.com/image.png" decoding="async" loading="lazy" width="1980" height="1080" alt="...">

Is that a typo or I'm missing something?

[Princesseuh]

Oops, you're right. Typo from copy pasting the proposal from my Obsidian vault, ha! Sorry for the confusion

[matthewp]

The ~/assets alias seems a little out of place here to me. We don't currently provide any aliases that I'm aware of. Given that this is just a convenience thing, I'd probably recommend that be in a separate proposal. The proposal doesn't specifically say, does ~/components also work? Is the alias ~/ pointing to srcDir? I would expect that to be the case, but the text here makes it seem like it's just ~/assets.

Aside from that, another concern would be that we start using the alias in documentation and it only works if you're app is built through create-astro. As much as possibly I think we need to avoid making create-astro a pseudo requirement of using Astro itself.

[Princesseuh]

Definitely fair! I'm not strict on this alias existing personally. The idea was to make it easier for users in Markdown to refer to assets (do I type src/assets or /src/assets or assets/? Can I only refer to src/assets relatively?)

The alias would in fact point to src, similar to other frameworks offering ~ as an alias.

[matthewp]

Given the below discussion (src/assets not having superpowers at the moment), I can definitely see the alias as a way to entice people to put images there and not in a nested folder in src/content. So given that I feel less strongly about omitting the alias.

[matthewp]

It's not clear to me, what is actually different about src/assets? Are images in this folder treated differently some how? The proposal starts by setting up the folder as being special, but later says that relative works the same way no matter where the files are located. Am I missing something? Is src/assets just a recommendation or a reserved folder for future features?

[Princesseuh]

It's both a philosophical and a technological thing:

• Philosophically, it sets a clear place for users to put assets. Currently, it's unclear for users if their assets are supposed to even be in src or if they should be in public. This folder is intended to answer this: Unless you have a specific use case, src/assets is the coolest and freshest place where source assets hang out. It definitely help (at least for me) to think of it as the companion of src/content, since it also has the same concerns (What is different about src/content?)
• Technologically, this gives us a stable reference to assets, this makes it easier for content management systems (including content collections) to manage and check the assets. Hence why, as the proposal says, only assets inside the src/assets folder can be checked by content collections.

It's easy to imagine in the future ex: an Astro CMS that allows you to manage all your assets in src/assets and easily link to them from content in src/content. Or, for the language tools to offer completions for assets automatically in relevant areas (ex: z.asset('') give you completions for all the assets present in the src/assets folder)

[FredKSchott]

I think the proposal would benefit from fleshing out the content collections <> assets story a bit more. There's one snippet that does explore this a bit:

---
cover: ~/assets/cover.png 
---

From some early conversations with Erika, I believe a goal would be that you could do this in your schema:

schema: z.object({
  cover: z.asset() // Note: conceptual name, probably not actually z.asset()
})

This would give you accurate errors if the asset you were referencing didn't exist.

One open question: I'm not sure if we want to support the import form cover: ~/assets/cover.png vs. a specific asset by name like cover: cover.png. I think it depends on whether we can support relative imports outside of the assets directory, and whether we want to.

[Princesseuh]

Currently the proposal has this:

In tandem with the src/assets folder, we'd like to introduce a way for users to specify that a specific property needs to refer to a valid asset from the src/assets folder. This would allow us to provide validation of the asset, think cover needs to be a png of size 240x240, including validating that the file actually exists.

Does this not answer your concern? I can add an example, but I'm not sure what else I would add to this snippet, as it seems to cover your comment.

[FredKSchott]

Got it, sorry I missed that. I think just mentioning it is okay for this stage, but would want to see it fleshed out when we get to implementation / full RFC later down the road.

[matthewp]

Ok, I think it's fine to reserve a folder name for future enhancements. We just need to make sure we document it that way, to eliminate confusion.

[tony-sull]

I didn't see any mention of the <Picture> component, will its API get simplified similarly or is it being removed?

[Princesseuh]

It's part of the "Non-goals of this proposal":

Non-goals of this proposal

• ...
• Picture component

We plan to look at it in a separate proposal since the API for it can be quite complicated (especially if we aim to support art directions!)

[tony-sull]

Oof, missed it while catching back up on the thread, sorry!

[tony-sull]

Since remote images aren't optimized, is the main benefit of using the <Image> component that alt, width, and height attributes are required as a runtime check?

I'm wondering if an update to the astro-jsx type definitions + enforcing that <Image /> is for local images only would make an even more clear line on when to use vs. not use the component - I could see us getting questions on why the component isn't always optimizing images

[Princesseuh]

Since remote images aren't optimized, is the main benefit of using the component that alt, width, and height attributes are required as a runtime check?

At the moment, yes! Remote images are out of scope for this specific proposal, but it doesn't mean they'll necessarily always be. We can definitely see use cases (images coming from CMS who don't offer image optimization, for instance)

I'm wondering if an update to the astro-jsx type definitions + enforcing that is for local images only would make an even more clear line on when to use vs. not use the component - I could see us getting questions on why the component isn't always optimizing images

In my opinion, changing astro-jsx is undesirable for this, as not everyone necessarily want those requirements on img (especially width and height, which have situations where you don't want them that we can't express purely through types). The more clear line is nice, but I could see it bitting us in the back later on if we do want to add remote images to Image

[matthewp]

This proposal has been promoted to stage 2! Please continue the discussion in the new issue: #475