Saltearse al contenido
Astro Astro

Imágenes

¡Astro ofrece varias formas para que uses imágenes en tu sitio, ya sea que estén almacenadas localmente dentro de tu proyecto, enlazadas desde una URL externa o gestionadas en un CMS o CDN!

Dónde guardar las imágenes

src/ vs. public/

Recomendamos que las imágenes locales se mantengan en src/ cuando sea posible, para que Astro pueda transformar, optimizar y empaquetarlas. Los archivos en el directorio /public siempre se sirven o copian tal como están en la carpeta de construcción, sin ningún procesamiento.

Tus imágenes locales almacenadas en src/ pueden ser utilizadas por todos los archivos en tu proyecto: .astro, .md, .mdx, .mdoc y otros frameworks UI. Las imágenes pueden almacenarse en cualquier carpeta, incluida junto a tu contenido.

Almacena tus imágenes en la carpeta public/ si deseas evitar cualquier tipo de procesamiento o para tener un enlace público directo a ellas.

Imágenes remotas

También puedes optar por almacenar tus imágenes de forma remota, en un sistema de gestión de contenido (CMS) o en una plataforma de gestión de assets digitales (DAM).

Para una protección adicional al tratar con fuentes externas, las imágenes remotas solo se procesarán desde fuentes de imágenes autorizadas especificadas en tu configuración. Sin embargo, cualquier imagen remota puede ser mostrada.

Astro puede obtener tus datos de forma remota utilizando APIs o mostrar imágenes desde su ruta completa de URL. Consulta nuestras guías de CMS para ejemplos de integración con servicios comunes.

Imágenes en archivos .astro

En archivos .astro, las imágenes locales deben ser importadas al archivo para poder ser utilizadas. Las imágenes remotas y las imágenes en public/ no requieren ser importadas

Importa y utiliza el componente incorporado <Image /> de Astro para imágenes optimizadas usando astro:assets. Alternativamente, la sintaxis de Astro admite escribir directamente una etiqueta HTML <img>, lo que omite el procesamiento de imágenes

src/pages/blog/MyImages.astro
---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="Un pájaro sentado sobre un nido de huevos."/>
<Image src="/images/bird-in-public-folder.jpg" alt="Un pájaro." width="50" height="50"/>
<Image src="https://example.com/remote-bird.jpg" alt="Un pájaro." width="50" height="50"/>


<img src={localBirdImage.src} alt="Un pájaro sentado sobre un nido de huevos.">
<img src="/images/bird-in-public-folder.jpg" alt="Un pájaro.">
<img src="https://example.com/remote-bird.jpg" alt="Un pájaro.">

Para importar imágenes dinámicamente desde la carpeta src/, consulta la siguiente receta:

Receta relacionada: Importa Imágenes Dinámicamente

<Image /> (astro:assets)

Utiliza el componente integrado <Image /> de Astro para mostrar versiones optimizadas de tus imágenes locales y imágenes remotas configuradas.

Las imágenes en la carpeta public/, así como las imágenes remotas no configuradas específicamente en tu proyecto, también se pueden usar con el componente Image, pero no se procesarán.

<Image /> puede transformar las dimensiones, el tipo de archivo y la calidad de una imagen local o remota autorizada para un control sobre la imagen que se muestra. La etiqueta resultante <img> incluye atributos alt, loading y decoding, e infiere las dimensiones de la imagen para evitar el Desplazamiento Acumulativo de Diseño (CLS).

src/components/MyComponent.astro
---
// Importa el componente Image y la imagen
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // La imagen es 1600x900
---


<!-- `alt` es obligatorio en el componente Imagen -->
<Image src={myImage} alt="Una descripción de mi imagen." />
<!-- Salida -->
<!-- La imagen está optimizada, se aplican los atributos adecuados-->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Una descripción de mi imagen."
/>

Actualmente, la característica integrada de assets no incluye un componente <Picture />.

En su lugar, puedes generar imágenes o componentes personalizados usando getImage() que utilicen los atributos HTML de imagen srcset y sizes o la etiqueta <picture> para la dirección de arte o para crear imágenes responsivas.

Propiedades

src (requerido)

El formato del valor src de tu archivo de imagen depende de dónde esté ubicado tu archivo de imagen:

  • Imágenes locales en src/ - también debes importar la imagen utilizando una ruta de archivo relativa o configurar y usar un alias de importación. Luego usa el nombre de importación como valor de src:

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    import myImportedImage from `../assets/my-local-image.png`
    ---
    <Image src={myImportedImage} alt="texto descriptivo" />

  • Imágenes en la carpeta public/ - utiliza la ruta de archivo de la imagen relativa a la carpeta public:

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    ---
    <Image
      src="/images/my-public-image.png"
      alt="texto descriptivo"
      width="200"
      height="150"
    />

  • Imágenes remotas - utiliza la URL completa de la imagen como valor de la propiedad:

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    ---
    <Image
      src="https://example.com/remote-image.jpg"
      alt="texto descriptivo"
      width="200"
      height="150" />
alt (requerido)

Utiliza el atributo alt requerido para proporcionar un texto alternativo descriptivo para las imágenes.

Si una imagen es meramente decorativa (es decir, no contribuye a la comprensión de la página), establece alt="" para que los lectores de pantalla y otras tecnologías de asistencia sepan que deben ignorar la imagen.

width y height (requerido para imágenes public/ y remotas)

Estas propiedades definen las dimensiones a utilizar para la imagen.

Cuando se utilizan imágenes locales en su relación de aspecto original, el width y height pueden inferirse automáticamente a partir del archivo fuente y son opcionales.

Sin embargo, ambas de estas propiedades son necesarias para imágenes remotas e imágenes almacenadas en tu carpeta public/, ya que Astro no puede analizar estos archivos.

densities
Agregado en: astro@3.3.0 Experimental

Una lista de densidades de píxeles para generar la imagen.

Si se proporciona, este valor se utilizará para generar un atributo srcset en la etiqueta <img>. No proporciones un valor para widths cuando utilices este valor.

Las densidades que sean iguales a los anchos mayores que la imagen original se ignorarán para evitar el escalado de la imagen.

src/components/MyComponent.astro
---
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png";
---
<Image src={myImage} width={myImage.width / 2} densities={[1.5, 2]} alt="Una descripción de mi imagen." />
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 1.5x
    /_astro/my_image.hash.webp 2x
  "
  alt="Una descripción de mi imagen"
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>
widths
Agregado en: astro@3.3.0 Experimental

Una lista de anchos para generar la imagen.

Si se proporciona, este valor se utilizará para generar un atributo srcset en la etiqueta <img>. También se debe proporcionar una propiedad sizes.

No proporciones un valor para densities cuando utilices este valor. Solo uno de estos dos valores se puede utilizar para generar un srcset.

Los anchos que sean mayores que la imagen original se ignorarán para evitar el escalado de la imagen.

---
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // La imagen es de 1600x900
---
<Image
  src={myImage}
  widths={[240, 540, 720, myImage.width]}
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`}
  alt="Una descripción de mi imagen."
/>
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 240w,
    /_astro/my_image.hash.webp 540w,
    /_astro/my_image.hash.webp 720w,
    /_astro/my_image.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="Una descripción de mi imagen."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>
format

Puedes opcionalmente indicar el tipo de archivo de imagen de salida que se va a utilizar.

Por defecto, el componente <Image /> producirá un archivo .webp.

quality

quality es una propiedad opcional que puede ser:

  • un preajuste (low, mid, high, max) que se normaliza automáticamente entre los formatos.
  • un número del 0 al 100 (interpretado de manera diferente entre los formatos).
Propiedades adicionales

Además de las propiedades mencionadas anteriormente, el componente <Image /> acepta todas las propiedades aceptadas por la etiqueta HTML <img>.

Por ejemplo, puedes proporcionar una propiedad class al elemento <img> final.

src/pages/index.astro
---
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png";
---


<!-- `alt` es obligatorio en el componente Imagen -->
<Image src={myImage} alt="" class="mi-clase" />
<!-- Salida -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="mi-clase"
  alt=""
/>

Estableciendo valores por defecto

Actualmente, no hay forma de especificar valores predeterminados para todos los componentes <Image />. Los atributos requeridos deben establecerse en cada componente individual.

Como alternativa, puedes envolver estos componentes en otro componente de Astro para reutilizarlos. Por ejemplo, podrías crear un componente para las imágenes de tus entradas de blog:

src/components/BlogPostImage.astro
---
import { Image } from 'astro:assets';


const {src, ...attrs} = Astro.props;
---
<Image src={src} {...attrs} />


<style>
  img :global(img), svg {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

<Picture />

Agregado en: astro@3.3.0

Usa el componente <Picture /> incorporado de Astro para mostrar una imagen receptiva con varios formatos y/o tamaños.

src/pages/index.astro
---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // La imagen es de 1600x900
---


<!-- `alt` es obligatorio en el componente Picture -->
<Picture src={myImage} formats={['avif', 'webp']} alt="Una descripción de mi imagen." />
<!-- Salida -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Una descripción de mi imagen."
  />
</picture>

Propiedades

<Picture /> acepta todas las propiedades del componente <Image />, más las siguientes:

formats

Un arreglo de formatos de imagen para usar en las etiquetas <source>. Las entradas se agregarán como elementos <source> en el orden en que se enumeran, y este orden determina qué formato se muestra. Para obtener el mejor rendimiento, enumera el formato más moderno primero (por ejemplo, webp o avif). Por defecto, esto se establece en ['webp'].

fallbackFormat

Formato que se utilizará como valor de respaldo para la etiqueta <img>.

El valor predeterminado es .png para imágenes estáticas, .gif para imágenes animadas y .svg para archivos SVG.

pictureAttributes

Un objeto de atributos que se agregarán a la etiqueta <picture>.

Usa esta propiedad para aplicar atributos al elemento <picture> externo. Los atributos aplicados al componente <Picture /> directamente se aplicarán al elemento <img> interno, excepto aquellos utilizados para la transformación de imágenes.

src/components/MyComponent.astro
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // La imagen es de 1600x900
---


<Picture src={myImage} alt="Una descripción de mi imagen." pictureAttributes={{style: "background-color: red;"}} />
<picture style="background-color: red;">
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    alt="Una descripción de mi imagen."
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>

<img>

La sintaxis de Astro también admite escribir directamente una etiqueta <img>, con control total sobre su salida final. Estas imágenes no se procesarán ni optimizarán.

Esta acepta todas las propiedades de la etiqueta HTML <img>, y la única propiedad requerida es src.

Imágenes locales en src/

Las imágenes locales deben ser importadas desde la ruta relativa al archivo .astro existente, o configurar y usar un alias de importación. Luego, puedes acceder a la propiedad src de la imagen y otras propiedades para usar en la etiqueta <img>.

Por ejemplo, utiliza las propiedades height y width propias de la imagen para evitar CLS y mejorar los Core Web Vitals.

src/pages/posts/post-1.astro
---
// importar imágenes locales
import myDog from `../../images/pets/local-dog.jpg`
---
// acceder a las propiedades de la imagen
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="Un perro ladrando." />

Los activos de imagen importados coinciden con la siguiente firma:

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

Imágenes en public/

Para las imágenes ubicadas dentro de public/, utiliza la ruta de archivo relativa a la carpeta public de la imagen como valor de src:

<img src="/images/public-cat.jpg" alt="Un gato dormiendo.">

Imágenes remotas

Para las imágenes remotas, utiliza la URL completa de la imagen como valor de src:

<img src="https://example.com/remote-cat.jpg" alt="Un gato dormiendo.">

Eligiendo <Image /> vs <img>

El componente <Image /> optimiza tu imagen e infiere el ancho y el alto (en imágenes locales) en función de la relación de aspecto original para evitar CLS. Sin embargo, solo funciona con ciertos formatos y no proporciona un elemento <picture>, ni admite srcset.

Utiliza el elemento HTML <img> cuando no puedas usar el componente <Image />, por ejemplo:

  • para formatos de imagen no admitidos
  • cuando no deseas que tu imagen se optimice mediante Astro
  • para acceder y cambiar el atributo src dinámicamente en el lado del cliente

Autorizando imágenes remotas

Puedes configurar listas de dominios y patrones de URL de origen de imágenes autorizados para la optimización de imágenes utilizando image.domains y image.remotePatterns. Esta configuración es una capa adicional de seguridad para proteger tu sitio al mostrar imágenes desde una fuente externa.

Remote images from other sources will not be optimized, but using the <Image /> component for these images will prevent Cumulative Layout Shift (CLS).

For example, the following configuration will only allow remote images from astro.build to be optimized:

astro.config.mjs
export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});

La siguiente configuración solo permitirá que las imágenes remotas provengan de hosts HTTPS:

astro.config.mjs
export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});

Utilizando imágenes de un CMS o CDN

Los CDNs de imágenes funcionan con todas las opciones de imágenes de Astro. Utiliza la URL completa de la imagen como atributo src en el componente <Image />, una etiqueta <img> o en la notación Markdown. Para la optimización de imágenes con imágenes remotas, también configura tus dominios autorizados o patrones de URL.

Alternativamente, si el CDN proporciona un SDK de Node.js, puedes utilizarlo en tu proyecto. Por ejemplo, el SDK de Cloudinary puede generar una etiqueta <img> con el src adecuado por ti.

Imágenes en archivos Markdown

Utiliza la sintaxis estándar de Markdown ![alt](src) en tus archivos .md. Esta sintaxis funciona con la API de servicio de imagenes de Astro para optimizar tus imágenes locales y las imágenes remotas autorizadas.

src/pages/post-1.md
# Mi página Markdown


<!-- Imagen local almacenada en src/assets/ -->
<!-- Utiliza una ruta de archivo relativa o un alias de importación -->
![Un cielo estrellado.](../assets/stars.png)


<!-- Imagen almacenada en public/images/ -->
<!-- Utiliza la ruta de archivo relativa a public/ -->
![Un cielo estrellado.](/images/stars.png)


<!-- Imagen remota en otro servidor -->
<!-- Utiliza la URL completa de la imagen -->
![Astro](https://example.com/images/remote-image.png)

La etiqueta <img> no es compatible para imágenes locales y el componente <Image /> no está disponible en archivos .md.

Si necesitas más control sobre los atributos de tus imágenes, te recomendamos utilizar el formato de archivo .mdx, que te permite incluir el componente <Image /> de Astro o una etiqueta JSX <img /> además de la sintaxis Markdown. Utiliza la integración MDX para agregar soporte para MDX en Astro.

Imágenes en archivos MDX

Puedes utilizar el componente <Image /> de Astro y las etiquetas JSX <img /> en tus archivos .mdx importando tanto el componente como tu imagen. Úsalos tal como se utilizan en archivos .astro.

Además, hay soporte para la sintaxis estándar de Markdown ![alt](src) sin necesidad de importación.

src/pages/post-1.mdx
---
title: Título de mi página
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';


# Mi Página MDX


// Imagen local almacenada en src/assets/
<Image src={rocket} alt="Un cohete en el espacio."/>
<img src={rocket.src} alt="Un cohete en el espacio." />
![A rocketship in space](../assets/rocket.png)


// Imagen almacenada en public/images/
<Image src="/images/stars.png" alt="Un cielo estrellado." />
<img src="/images/stars.png" alt="Un cielo estrellado." />
![Un cielo estrellado.](/images/stars.png)


// Imagen remota en otro servidor
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)

Imágenes en Colecciones de Contenido

Puedes declarar una imagen asociada para una entrada de colecciones de contenido, como la imagen de portada de una entrada de blog, en tu metadatos utilizando su ruta relativa a la carpeta actual:

src/content/blog/my-post.md
---
title: "Mi primera entrada en el blog"
cover: "./firstpostcover.jpeg" # se resolverá como "src/content/blog/firstblogcover.jpeg"
coverAlt: "Una fotografía de una puesta de sol detrás de una cordillera."
---


Esta es una entrada de blog

El helper image para el esquema de colecciones de contenido te permite validar los metadatos de la imagen utilizando Zod.

src/content/config.ts
import { defineCollection, z } from "astro:content";


const blogCollection = defineCollection({
  schema: ({ image }) => z.object({
    title: z.string(),
    cover: image().refine((img) => img.width >= 1080, {
      message: "¡La imagen de portada debe tener al menos 1080 píxeles de ancho!",
    }),
    coverAlt: z.string(),
  }),
});


export const collections = {
  blog: blogCollection,
};

La imagen se importará y transformará en metadatos, lo que te permitirá pasarlo como src a <Image/>, <img> o getImage().

El siguiente ejemplo muestra una página de índice de un blog que muestra la foto de portada y el título de cada entrada del blog a partir del esquema anterior:

src/pages/blog.astro
---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---


{
  allBlogPosts.map((post) => (
    <div>
      <Image src={post.data.cover} alt={post.data.coverAlt} />
      <h2>
        <a href={"/blog/" + post.slug}>{post.data.title}</a>
      </h2>
    </div>
  ))
}

Imágenes en componentes de frameworks UI

Cuando añadas imágenes en un componente de un framework UI, utiliza la sintaxis de imagen propia del framework para renderizar una imagen (p. ej. <img/> en JSX, <img> en Svelte).

Las imágenes locales deben ser importadas primero para acceder a sus propiedades de imagen como src.

src/components/ReactImage.jsx
import stars from "../assets/stars.png"


export default function ReactImage () {
  return (
    <img src={stars.src} alt="Un cielo estrellado." />
  )
}
src/components/SvelteImage.svelte
<script>
  import stars from '../assets/stars.png'
</script>


<img src={stars.src} alt="Un cielo estrellado." />

Pasando el componente Image

El componente <Image />, al igual que cualquier otro componente de Astro, no está disponible para los componentes de frameworks UI.

Sin embargo, puedes pasar el contenido estático generado por <Image /> a un componente de framework dentro de un archivo .astro como hijos o utilizando un <slot/> nombrado:

ImageWrapper.astro
---
import ReactComponent from './ReactComponent.jsx';
import { Image } from "astro:assets"
import stars from "~/stars/docline.png";
---


<ReactComponent>
  <Image src={stars} alt="Un cielo estrellado." />
</ReactComponent>

Generando imágenes con getImage()

La función getImage() está destinada a generar imágenes que se utilizarán en otro lugar que no sea directamente en HTML, por ejemplo, en una Ruta API. También te permite crear tu propio componente <Image /> personalizado.

Receta relacionada: Construir un componente de imagen personalizado

getImage() recibe un objeto de opciones con las mismas propiedades que el componente Image (excepto alt).

---
import { getImage } from "astro:assets";
import myBackground from "../background.png"


const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---


<div style={`background-image: url(${optimizedBackground.src});`}></div>

Devuelve un objeto con las siguientes propiedades:

{
  options: {...} // Parámetros originales pasados
  src: "https//..." // Ruta a la imagen generada
  attributes: {...} // Atributos HTML adicionales necesarios para representar la imagen (width, height, style, etc..)
}

Texto Alt

No todos los usuarios pueden ver las imágenes de la misma manera, por lo que la accesibilidad es una preocupación especialmente importante al utilizar imágenes. Utiliza el atributo alt para proporcionar texto alternativo descriptivo para las imágenes.

Este atributo es obligatorio para el componente <Image />. <Image /> lanzará un error si no se proporciona texto alternativo.

Si la imagen es meramente decorativa (es decir, no contribuye a la comprensión de la página), establece alt="" para que los lectores de pantalla sepan que deben ignorar la imagen.

Servicio de imágenes por defecto

Sharp es el servicio de imágenes por defecto utilizado para astro:assets.

Configura Squoosh

Si prefieres utilizar Squoosh para transformar tus imágenes, actualiza tu configuración con lo siguiente:

astro.config.mjs
import { defineConfig, squooshImageService } from 'astro/config';


export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});

Configura el servicio no-op de paso

Si tu adaptador para el modo server o hybrid no admite la optimización de imágenes integrada de Astro con Squoosh y Sharp (por ejemplo, Deno, Cloudflare), puedes configurar un servicio de imágenes sin acción para permitirte utilizar los componentes <Image /> y <Picture />. Ten en cuenta que Astro no realiza ninguna transformación ni procesamiento de imágenes en estos entornos. Sin embargo, aún puedes disfrutar de otros beneficios de usar astro:assets, como la ausencia de Desplazamiento Acumulativo de Diseño (CLS), el atributo alt obligatorio y una experiencia de autoría coherente.

Configura el servicio passthroughImageService() para evitar el procesamiento de imágenes de Squoosh y Sharp:

astro.config.mjs
import { defineConfig, passthroughImageService } from 'astro/config';


export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

Integraciones comunitarias

Existen varias integraciones de imágenes de la comunidad de terceros para optimizar y trabajar con imágenes en tu proyecto de Astro.

Actualizar a v3.0 desde v2.x

astro:assets ya no está detrás de una bandera experimental en Astro v3.0.

<Image /> es ahora un componente integrado y se ha eliminado la integración anterior @astrojs/image.

Estos y otros cambios relacionados con el uso de imágenes en Astro pueden causar algunos cambios disruptivos al actualizar tu proyecto de Astro de una versión anterior.

Sigue las instrucciones a continuación según corresponda para actualizar un proyecto de Astro v2.x a v3.0.

Actualizar desde experimental.assets

Si habías habilitado previamente la bandera experimental para astro:assets, deberás actualizar tu proyecto para Astro v3.0, que ahora incluye las características de assets de forma predeterminada.

Eliminar la bandera experimental.assets

Elimina la bandera experimental:

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  experimental: {
    assets: true
  }
});

Si es necesario, también actualiza tu archivo src/env.d.ts para reemplazar la referencia astro/client-image por astro/client:

src/env.d.ts
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />

Eliminar el alias de importación ~/assets

Este alias de importación ya no se incluye por defecto con astro:assets. Si estabas usando este alias con assets experimentales, debes convertirlos a rutas de archivo relativas o crear tus propios alias de importación.

src/pages/posts/post-1.astro
---
import rocket from '~/assets/rocket.png'
import rocket from '../../assets/rocket.png';
---

Agrega soporte sencillo para assets en Cloudflare, Deno, Vercel Edge y Netlify Edge

Astro v3.0 permite que astro:assets funcione sin errores en Cloudflare, Deno, Vercel Edge y Netlify Edge, que no admiten la optimización de imágenes integrada de Astro con Squoosh y Sharp. Ten en cuenta que Astro no realiza ninguna transformación ni procesamiento de imágenes en estos entornos. Sin embargo, aún puedes disfrutar de otros beneficios de usar astro:assets, como la ausencia de Desplazamiento Acumulativo de Diseño (CLS), el atributo alt obligatorio y una experiencia de autoría coherente.

Si antes evitaste usar astro:assets debido a estas limitaciones, ahora puedes usarlo sin problemas. Puedes configurar el servicio de imágenes sin acción para optar explícitamente por este comportamiento:

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
});

Decide dónde almacenar tus imágenes

Consulta la guía de Imágenes para ayudarte a decidir dónde almacenar tus imágenes. Es posible que desees aprovechar las nuevas opciones para almacenar tus imágenes con la flexibilidad adicional que astro:assets ofrece. Por ejemplo, las imágenes relativas desde la carpeta src/ de tu proyecto ahora pueden ser referenciadas en Markdown, MDX y Markdoc utilizando la sintaxis estándar de Markdown ![alt](src).

Actualiza las etiquetas existentes <img>

Anteriormente, importar una imagen devolvía un string con la ruta de la imagen. Los assets de imagen importados coinciden con la siguiente firma:

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

Debes actualizar el atributo src de cualquier etiqueta <img> existente (incluyendo cualquier imagen en componentes de frameworks UI) y también puedes actualizar otros atributos que ahora están disponibles para ti a partir de la imagen importada.

src/components/MyComponent.astro
---
import rocket from '../images/rocket.svg';
---
<img src={rocket} width="250" height="250" alt="Un cohete en el espacio." />


<img src={rocket.src} width={rocket.width} height={rocket.height} alt="Un cohete en el espacio." />

Actualiza tus archivos Markdown, MDX y Markdoc

Las imágenes relativas desde la carpeta src/ de tu proyecto ahora pueden ser referenciadas en Markdown, MDX y Markdoc utilizando la sintaxis estándar de Markdown ![alt](src).

Esto te permite mover tus imágenes desde el directorio public/ a la carpeta src/ de tu proyecto, donde ahora serán procesadas y optimizadas. Tus imágenes existentes en public/ y las imágenes remotas siguen siendo válidas, pero no son optimizadas por el proceso de compilación de Astro.

src/pages/posts/post-1.md
# Mi página Markdown


<!-- ¡Imágenes locales ahora posibles! -->
![Un cielo estrellado](../../images/stars.png)


<!-- ¡Mantén tus imágenes junto a tu contenido! -->
![Un cielo estrellado](./stars.png)

Si necesitas más control sobre los atributos de tu imagen, te recomendamos usar el formato de archivo .mdx, que te permite incluir el componente <Image /> de Astro o una etiqueta JSX <img /> además de la sintaxis Markdown. Utiliza la integración de MDX para agregar soporte para MDX a Astro.

Elimina @astrojs/image

Si estabas utilizando la integración de imágenes en Astro v2.x, completa los siguientes pasos:

  1. Elimina la integración @astrojs/image.

    Debes eliminar la integración desinstalándola y luego eliminándola de tu archivo astro.config.mjs.

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import image from '@astrojs/image';
    

    export default defineConfig({
      integrations: [
        image(),
      ]
    })

  2. Actualiza los tipos (si es necesario).

    Si tenías tipos especiales configurados para @astrojs/image en src/env.d.ts, es posible que necesites cambiarlos de nuevo a los tipos predeterminados de Astro si la actualización a la versión 3 no completó este paso por ti.

    src/env.d.ts
     /// <reference types="@astrojs/image/client" />
     /// <reference types="astro/client" />

    Del mismo modo, actualiza tsconfig.json si es necesario:

    tsconfig.json
    {
      "compilerOptions": {
        "types": ["@astrojs/image/client"]
        "types": ["astro/client"]
      }
    }

  3. Migra cualquier componente <Imagen /> existente.

    Cambia todas las declaraciones de import de @astrojs/image/components a astro:assets para poder usar el nuevo componente integrado <Image />.

    Elimina cualquier atributo del componente que no sean propiedades de assets de imagen actualmente admitidas.

    Por ejemplo, aspectRatio ya no es compatible, ya que ahora se infiere automáticamente a partir de los atributos width y height.

    src/components/MyComponent.astro
    ---
    import { Image } from '@astrojs/image/components';
    import { Image } from 'astro:assets'
    import localImage from "../assets/logo.png";
    const localAlt = "El logo de Astro";
    ---
    

    <Image
      src={localImage}
      width={300}
      aspectRatio="16:9"
      alt={localAlt}
    />

  4. Elimina cualquier componente <Picture /> existente.

    Actualmente, la función de assets integrada no incluye un componente <Picture />.

    En su lugar, puedes utilizar los atributos de imagen HTML srcset y sizes, o la etiqueta <picture> para dirección de arte o para crear imágenes responsivas.

  5. Elige un servicio de imágenes predeterminado.

    Sharp es ahora el servicio de imágenes predeterminado utilizado para astro:assets. Si deseas utilizar Sharp, no se requiere ninguna configuración.

    Si prefieres utilizar Squoosh para transformar tus imágenes, actualiza tu configuración con la siguiente opción image.service:

    astro.config.mjs
    import { defineConfig, squooshImageService } from 'astro/config';
    

    export default defineConfig({
      image: {
        service: squooshImageService(),
      },
    });

Actualiza los esquemas de Colecciones de Contenido

Ahora puedes declarar una imagen asociada para una entrada de colecciones de contenido, como la imagen de portada de una entrada de blog, en tu metadatos usando su ruta relativa a la carpeta actual.

El nuevo helper image para colecciones de contenido te permite validar los metadatos de la imagen utilizando Zod. Aprende más sobre cómo usar imágenes en colecciones de contenido

En Astro v3.0, si tienes que conservar el antiguo comportamiento de importación para las imágenes y requieres una representación de tipo string de la URL de la imagen, añade ?url al final de la ruta de la imagen al importarla. Por ejemplo:

src/pages/blog/MyImages.astro
---
import Sprite from '../assets/logo.svg?url';
---
  <svg>
    <use xlink:href={Sprite + '#cart'} />
  </svg>

Este enfoque garantiza que obtengas el string URL. Ten en cuenta que durante el desarrollo, Astro utiliza una ruta src/, pero al compilar, genera rutas hash como /_astro/cat.a6737dd3.png.

Si prefieres trabajar directamente con el objeto de imagen, puedes acceder a la propiedad .src. Este enfoque es el mejor para tareas como la gestión de las dimensiones de la imagen para las métricas de Core Web Vitals y la prevención de CLS.

Si estás en transición al nuevo comportamiento de importación, combinar ?url y .src puede ser el método adecuado para el manejo de imágenes sin problemas.