A plan for a core image story #468
Replies: 13 comments 45 replies
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
|
One thing that I don't see mentioned here is how we'll handle the native |
Beta Was this translation helpful? Give feedback.
-
|
@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
Questions
|
Beta Was this translation helpful? Give feedback.
-
|
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 So I agree with what @wassfila is adding here. Start simply by supporting relative assets to MD/MDX. |
Beta Was this translation helpful? Give feedback.
-
|
Great stuff,
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. |
Beta Was this translation helpful? Give feedback.
-
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
The 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 |
Beta Was this translation helpful? Give feedback.
-
|
It's not clear to me, what is actually different about |
Beta Was this translation helpful? Give feedback.
-
|
I didn't see any mention of the |
Beta Was this translation helpful? Give feedback.
-
|
Since remote images aren't optimized, is the main benefit of using the I'm wondering if an update to the |
Beta Was this translation helpful? Give feedback.
-
|
This proposal has been promoted to stage 2! Please continue the discussion in the new issue: #475 |
Beta Was this translation helpful? Give feedback.

Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Body
Summary
This proposal aims to outline a plan for a core story for images in Astro, doing so by:
src/content)Background & Motivation
src/assetsfolderUsing images in Astro is currently a bit confusing. Should my images go in
publicorsrc? How do I refer to them?For this, we'd like to introduce a
src/assetsfolder. 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 necessitatingtsconfig.jsonchanges, 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/assetsfolder, we'd like to introduce a way for users to specify that a specific property needs to refer to a valid asset from thesrc/assetsfolder. This would allow us to provide validation of the asset, thinkcover needs to be a png of size 240x240, including validating that the file actually exists.Facts
src/assetsis supported and they would be optimized, like before.src/assetsis also supported (ex:) in addition to thesrc/assetsfolder (ex:)publicfolder 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.src/assetsfolder. Remote images are currently out of scope and still need to be referred to using az.string.srcand they'll be optimized.![]syntax and refer to images insrc/assetsor relative to the file and they'll be optimized.src/assets.Image component
(see #447 for an earlier version of this proposal)
The current
Imagecomponent can be confusing to use at time. Why do I need to set anaspectRatio? (what even is the aspect ratio of my image?) Why is my image getting cropped? What format should I use? What doesqualitymeans?width, height and aspectRatio
We'd like to make it so less properties are needed in general. In most cases, the
widthandheightwould 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
aspectRatioproperty, instead preferring that users manually set bothwidthandheight. Combined with [[#Better behaviour for resizing images]], we believe that this will lead to a more consistant and easier to resonate about experience.format
formatwould be set towebpby 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/imagewould 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, theobject-fitandobject-positionCSS properties can be used.For users used to other frameworks, this is a similar behaviour to the one offered by NextJS's
next/imageand Eleventy'seleventy-img.Facts
src. Remote images (ex:http://example.com/image.png,/image.pngor${import.meta.env.BASE_URL}/image.png) would however requirewidthandheightto be set manually.srccan be a dynamic import, but be aware that it must respect Vite's limitations on dynamic importsformatwould be set towebpby 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 doformat={myImage.format}.qualitynow accepts two types of values, either a preset (low | mid | high | max) or a specific number (0 - 100).altis a required property in all cases. It can be explicitly set to"", for cases where an alt-text is not required.loading="lazy"anddecoding="async", with possibility to override as needed.src,width,height,quality, and all the properties natively available on theimgtag (alt,loading,decoding,styleetc)Shape of ESM imports
Currently, importing images in Astro returns a simple
stringwith the path of the image. The@astrojs/imageintegration enhance this by instead returning the following shape:{src: string, width: number, height: number, format: string}, allowing users to easily constructimgtags with no CLS: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.tswith the type changes needed for this.Goals
alt,loading,decoding)Non-goals of this proposal
srcset.svgsupportWe 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
Imagecomponent 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
Basic image from
src/assetsSource
Result
Resized image from
src/assetsSource
Result
Source
Result
Basic remote image
Source
Result (3rd example)
Markdown
Source
Source image is a .png of 640x960
Result
Result is a .webp of 640x960
Source
Result
Beta Was this translation helpful? Give feedback.
All reactions