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.
-
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.
-
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/assets
folderUsing images in Astro is currently a bit confusing. Should my images go in
public
orsrc
? 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 necessitatingtsconfig.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 thesrc/assets
folder. 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/assets
is supported and they would be optimized, like before.src/assets
is also supported (ex:![...](./image.png)
) in addition to thesrc/assets
folder (ex:![...](~/assets/image.png)
)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.src/assets
folder. Remote images are currently out of scope and still need to be referred to using az.string
.src
and they'll be optimized.![]
syntax and refer to images insrc/assets
or relative to the file and they'll be optimized.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 anaspectRatio
? (what even is the aspect ratio of my image?) Why is my image getting cropped? What format should I use? What doesquality
means?width, height and aspectRatio
We'd like to make it so less properties are needed in general. In most cases, the
width
andheight
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 bothwidth
andheight
. 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 towebp
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, theobject-fit
andobject-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'seleventy-img
.Facts
src
. Remote images (ex:http://example.com/image.png
,/image.png
or${import.meta.env.BASE_URL}/image.png
) would however requirewidth
andheight
to be set manually.src
can be a dynamic import, but be aware that it must respect Vite's limitations on dynamic importsformat
would be set towebp
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 doformat={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.loading="lazy"
anddecoding="async"
, with possibility to override as needed.src
,width
,height
,quality
, and all the properties natively available on theimg
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 constructimg
tags 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.ts
with the type changes needed for this.Goals
alt
,loading
,decoding
)Non-goals of this proposal
srcset
.svg
supportWe 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
Basic image from
src/assets
Source
Result
Resized image from
src/assets
Source
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