Built-in optimized asset support is enabled in Astro behind an experimental flag. This built-in feature will eventually replace the optional
The new assets experience currently features:
- A new built-in
- Relative images with automatic optimization in Markdown, MDX, and Markdoc
- Integration with content collections
- Improved error messages and types
Enabling Assets in your ProjectSection titled Enabling Assets in your Project
Enabling assets may cause some breaking changes in your project. It may also require some manual changes to take advantage of new features.
Please check every section below to avoid errors and to get the most out of using the experimental assets option!
Update ConfigSection titled Update Config
To enable built-in asset support, add the following lines to your
astro.config.mjs configuration file:
When you next run Astro, it will update your
src/env.d.ts file to configure types for you. To do this manually, replace the
astro/client reference with
Move your images to Section titled Move your images to src/assets/
src/assets/, which Astro will recognize as your new assets folder.
We recommend storing all images to be optimized in the
src/assets/ directory, although this location is optional.
Your images stored in
src/assets/ can be used by components (
.mdx, and other UI frameworks) and in Markdown files.
Update existing Section titled Update existing <img> tags
Previously, importing an image would return a simple
string with the path of the image. With the new
image features enabled, imported image assets now match the following signature:
You must update the
src attribute of any existing
<img> tags, and you may also update other attributes that are now available to you from the imported image.
Update your Markdown, MDX, and Markdoc filesSection titled Update your Markdown, MDX, and Markdoc files
Relative images can now be referenced in Markdown, MDX, and Markdoc files. These will automatically be optimized and hashed by Astro’s build process.
This allows you to move your images from the
public/ directory to the new, reserved
src/assets/ directory or move them near your Markdown, MDX, or Markdoc files. (See the URL path of these built images in the example below.)
Your existing images in
public/ and remote images are still valid but are not automatically optimized by Astro’s build process.
Convert from Section titled Convert from @astrojs/image
Built-in asset support is incompatible with the
To avoid errors in your project, complete the following steps:
You must remove the integration by uninstalling and then removing it from your
Migrate any existing
astro:assetsto use the new built-in
Remove any component attributes that are not currently supported image asset properties.
aspectRatiois no longer supported, as it is now automatically inferred from the
Remove any existing
Currently, the built-in assets feature does not include a
Instead, you can use the HTML image attributes
<picture>tag for art direction or to create responsive images.
Update content collections schemasSection titled Update content collections schemas
You can now declare images in your frontmatter as their paths relative to the current folder.
image helper for content collections lets you validate the image metadata using Zod.
The image will be imported and transformed into metadata that matches the signature of imported images, allowing you to pass it as a
getImage(). A blog index page might render the cover photo and title of each blog post:
Section titled astro:assets module
Enabling asset support allows you to access the
astro:assets module. This module exposes the following features:
<Image />(available in
.json the server)
Section titled <Image /> (astro:assets)
<Image /> (
<Image /> component generates an
This component can transform an image’s dimensions, file type, and quality to produce an optimized image. The resulting
<img> tag will include the correct
height attributes to avoid Cumulative Layout Shift (CLS).
Import images from a relative file path or import alias in any component file and then use the import as the
<Image /> component’s
PropertiesSection titled Properties
width and heightSection titled width and height
These properties define the dimensions to use for the image.
When using local images in their original aspect ratio, the
height can be automatically inferred from the source file and are optional. However, both of these properties are required for remote images.
formatSection titled format
You can optionally state the image file type to be used. The default file format used is
qualitySection titled quality
quality is an optional property that can either be:
- a preset (
max) that is automatically normalized between formats.
- a number from
100(interpreted differently between formats).
alt (required)Section titled alt (required)
alt attribute to provide descriptive alt text for images.
This attribute is required for the
<Image /> component. This component will throw an error if no alt text is provided.
If the image is merely decorative (i.e. doesn’t contribute to the understanding of the page), set
alt="" so that screen readers know to ignore the image.
Additional propertiesSection titled Additional properties
In addition to the properties above, the
<Image /> component accepts all properties accepted by the HTML
For example, you can provide a
class to the final
Section titled getImage() (astro:assets)
This function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an API Route. It also allows you to create your own custom
<Image /> component.
getImage() takes an options object with the same properties as the Image component (except
It returns an object with the following properties:
Using sharpSection titled Using sharp
If you’re deploying to a Node environment, you may want to use sharp, which offers faster performance but requires Node. To use sharp, first install it:
Then, enable Astro’s sharp image service in your config: