Assets (Experimental)

Built-in optimized asset support is enabled in Astro behind an experimental flag. This built-in feature will eventually replace the optional @astrojs/image integration.

The new assets experience currently features:

• A new built-in <Image /> component
• Relative images with automatic optimization in Markdown, MDX, and Markdoc
• Integration with content collections
• Improved error messages and types

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!

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 astro/client-image:

Create src/assets/, which Astro will recognize as your new assets folder.

We recommend storing all images to be optimized in the src/assets/ directory to make use of our official ~/assets alias, although this location is optional. If you don’t know where to put your images, or if you’re building a product around Astro (e.g. a CMS), you can put your images there and we promise we won’t break them! But, images can be stored anywhere, including alongside your content, if you prefer.

Your images can be used by components (.astro, .mdx, and other UI frameworks) and in Markdown files.

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.

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.

Built-in asset support is incompatible with the @astrojs/image integration.

To avoid errors in your project, complete the following steps:

1. Remove the @astrojs/image integration.

   You must remove the integration by uninstalling and then removing it from your astro.config.mjs file.

2. Migrate any existing <Image /> components.

   Change all import statements from @astrojs/image/components to astro:assets to use the new built-in <Image /> component.

   Remove any component attributes that are not currently supported image asset properties.

   For example aspectRatio is no longer supported, as it is now automatically inferred from the width and height attributes.

   src/components/MyComponent.astro

3. Remove any existing <Picture /> components

   Currently, the built-in assets feature does not include a <Picture /> component.

   Instead, you can use the HTML image attributes srcset and sizes or the <picture> tag for art direction or to create responsive images.

You can now declare images in your frontmatter as their paths relative to the current folder.

A new 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 src to <Image/> or getImage(). A blog index page might render the cover photo and title of each blog post:

Enabling asset support allows you to access the astro:assets module. This module exposes the following features:

• <Image /> (available in .astro and .mdx files)
• getImage() (available in .astro, .mdx, .ts, .js on the server)

The <Image /> component generates an <img> tag.

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 width and 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 src attribute.

These properties define the dimensions to use for the image.

When using local images in their original aspect ratio, the width and height can be automatically inferred from the source file and are optional. However, both of these properties are required for remote images.

You can optionally state the image file type to be used. The default file format used is webp.

quality is an optional property that can either be:

• a preset (low, mid, high, max) that is automatically normalized between formats.
• a number from 0 to 100 (interpreted differently between formats).

Use the 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.

In addition to the properties above, the <Image /> component accepts all properties accepted by the HTML <img> tag.

For example, you can provide a class to the final img element.

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 alt).

It returns an object with the following properties:

By default, Astro uses Squoosh to transform your images.

If you’re building a static site or deploying an SSR site to a Node environment, we recommend using sharp, which offers faster performance but requires Node. To use sharp, first install it:

npmpnpmYarn

Terminal window

Then, enable Astro’s sharp image service in your config: