@astrojs/image

⚠️ ¡Esta integración es todavía experimental! Actualmente sólo es compatible con entornos de nodos, ¡pero estate atento a la compatibilidad con Deno en el futuro!

Esta integración de Astro facilita la optimización de imágenes en tu proyecto de Astro, ¡con soporte completo para construcciones de SSG (Static Site Generator) y renderizado en el lado del servidor!

Las imágenes juegan un papel importante en el rendimiento general y la usabilidad del sitio. Servir imágenes con el tamaño adecuado marca la diferencia, pero a menudo es complicado automatizar este proceso.

Esta integración proporciona los componentes <Image /> y <Picture>, así como un transformador de imágenes básico, con soporte completo para sitios estáticos y renderizado en el lado del servidor. El transformador de imágenes incorporado también es reemplazable, abriendo la puerta a futuras integraciones que funcionen con tu servicio de imágenes alojado favorito.

Junto con nuestra integración, recomendamos instalar sharp cuando sea apropiado.

El transformador de imágenes predeterminado de @astrojs/image está basado en Squoosh y utiliza bibliotecas de WebAssembly para admitir la mayoría de los entornos de implementación, incluidos aquellos que no admiten sharp, como StackBlitz.

Para obtener compilaciones más rápidas y un control más preciso de las transformaciones de imagen, instala sharp además de @astrojs/image si

• Estás construyendo un sitio estático con Astro.
• Estás utilizando un host de despliegue SSR compatible con NodeJS mediante @astrojs/netlify/functions, @astrojs/vercel/serverless o @astrojs/node.

Ten en cuenta que @astrojs/image no es compatible actualmente con

• Cloudflare SSR
• @astrojs/deno
• @astrojs/netlify/edge-functions
• @astrojs/vercel/edge

La herramienta de línea de comandos astro add automatiza la instalación por ti. Ejecuta uno de los siguientes comandos en una nueva ventana de terminal. (Si no estás seguro de qué gestor de paquetes estás usando, ejecuta el primer comando.) Luego, sigue las instrucciones y escribe “y” en la terminal (es decir, “sí”) para cada uno.

# Usando NPM
npx astro add image
# Usando Yarn
yarn astro add image
# Usando PNPM
pnpm astro add image

Si tienes algún problema, no dudes en informarnos en GitHub y prueba los pasos de instalación manual a continuación.

Primero, instala el paquete @astrojs/image utilizando tu gestor de paquetes. Si estás utilizando npm o no estás seguro, ejecuta lo siguiente en tu terminal:

npm install @astrojs/image

Luego, aplica esta integración a tu archivo astro.config.* utilizando la propiedad integrations:

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

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

Primero, instala el paquete sharp utilizando tu administrador de paquetes. Si estás utilizando npm o no estás seguro, ejecuta lo siguiente en la terminal:

npm install sharp

A continuación, actualiza la integración en tu archivo astro.config.* para utilizar el transformador de imágenes integrado sharp.

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

export default defineConfig({
  // ...
  integrations: [image({
    serviceEntryPoint: '@astrojs/image/sharp'
  })],
})

Para tener la mejor experiencia de desarrollo, agrega las definiciones de tipos de las integraciones a tu archivo env.d.ts del proyecto.

// Reemplaza `astro/client` con `@astrojs/image/client`
/// <reference types="@astrojs/image/client" />

O, alternativamente, si tu proyecto está utilizando los tipos a través de un archivo tsconfig.json

{
  "compilerOptions": {
    // Reemplaza `astro/client` con `@astrojs/image/client`
    "types": ["@astrojs/image/client"]
  }
}

---
import { Image, Picture } from '@astrojs/image/components';
---

Los transformadores de imagen incluidos admiten el redimensionamiento de imágenes y la codificación en diferentes formatos de imagen. Los servicios de imágenes de terceros también podrán agregar soporte para transformaciones personalizadas (p. ej: blur, filter, rotate, etc).

Los componentes <Image /> y <Picture /> de Astro requieren el atributo alt, que proporciona texto descriptivo para las imágenes. Se mostrará un aviso si falta el texto alternativo, y en futuras versiones de la integración se generará un error si no se proporciona texto alternativo.

Si la imagen es simplemente decorativa (es decir, no contribuye a la comprensión de la página), establece alt="" para que la imagen sea correctamente entendida y omitida por los lectores de pantalla.

El componente integrado <Image /> se utiliza para crear una etiqueta <img /> optimizada tanto para imágenes remotas accedidas por URL como para imágenes locales importadas desde el directorio src/ de tu proyecto.

Además de las propiedades específicas del componente, cualquier atributo HTML válido para la etiqueta<img /> incluido en el componente <Image /> se incluirá en la etiqueta <img /> generada.

Tipo: string | ImageMetadata | Promise<ImageMetadata>
Por defecto: true

Fuente del archivo de imagen original.

Para imágenes remotas, proporciona la URL completa. (p. ej. src="https://astro.build/assets/blog/astro-1-release-update.avif")

Para imágenes ubicadas en el directorio src/ de tu proyecto, utiliza la ruta del archivo relativa al directorio src/. (p. ej. src="../assets/source-pic.png")

Para imágenes ubicadas en el directorio public/, utiliza la ruta URL relativa al directorio public/. (p. ej. src="/images/public-image.jpg"). Estas funcionan como imágenes remotas.

Tipo: string
Por defecto: true

Define una descripción alternativa de texto de la imagen.

Establécelo como un string vacio (alt="") si la imagen no es una parte clave del contenido (p. ej, si es una decoración o un píxel de seguimiento).

Tipo: 'avif' | 'jpeg' | 'jpg' | 'png' | 'svg' | 'webp'
Por defecto: undefined

El formato de salida que se utilizará en la imagen optimizada. Se utilizará el formato de la imagen original si no se proporciona el valor format.

Esta propiedad es obligatoria para imágenes remotas cuando se utiliza el transformador de imágenes predeterminado Squoosh, esto se debe a que no se puede inferir el formato original.

A partir de la versión 0.15.0, puedes utilizar el componente <Image /> cuando trabajas con imágenes SVG, pero la opción svg solo se puede utilizar cuando la imagen original es un archivo .svg. Otros formatos de imagen (como .png o .jpg) cannot be converted into vector images. La imagen .svg en sí no será transformada, pero la etiqueta <img /> final será optimizada correctamente por la integración.

Tipo: number
Por defecto: undefined

La calidad de compresión utilizada durante la optimización. El servicio de imágenes utilizará su propia calidad por defecto dependiendo del formato de la imagen si no se proporciona.

Tipo: number
Por defecto: undefined

La altura deseada de la imagen de salida. Combínalo con width para recortar la imagen a un tamaño exacto, o con aspectRatio para calcular y recortar automáticamente el ancho.

Las dimensiones son opcionales para las imágenes locales. Si no se proporcionan, se utilizará el tamaño original de la imagen.

Para las imágenes remotas, incluyendo las imágenes en la carpeta public/, la integración necesita poder calcular las dimensiones de la imagen optimizada. Esto se puede hacer proporcionando width y height o proporcionando una dimensión y un aspectRatio.

Tipo: number
Por defecto: undefined

La altura deseada de la imagen de salida. Combínalo con width para recortar la imagen a un tamaño exacto, o con aspectRatio para calcular y recortar automáticamente el ancho.

Las dimensiones son opcionales para las imágenes locales. Si no se proporcionan, se utilizará el tamaño original de la imagen.

Para las imágenes remotas, incluyendo las imágenes en la carpeta public/, la integración necesita poder calcular las dimensiones de la imagen optimizada. Esto se puede hacer proporcionando width y height o proporcionando una dimensión y un aspectRatio.

Tipo: number | string
Por defecto: undefined

La relación de aspecto deseada de la imagen de salida. Se combina con width o height para calcular automáticamente y recortar la otra dimensión.

Se puede proporcionar un string en la forma de {width}:{height}, por ejemplo: 16:9 o 3:4.

También se puede proporcionar un number, lo cual es útil cuando el aspect ratio se calcula en tiempo de generación. Esto puede ser un número en línea como 1.777 o en línea como una expresión JSX como aspectRatio={16/9}.

Para imágenes remotas, incluidas las imágenes en la carpeta public/, la integración necesita poder calcular las dimensiones de la imagen optimizada. Esto se puede hacer proporcionando width y height o proporcionando una dimensión y un aspectRatio.

Tipo: ColorDefinition
Por defecto: undefined

Esto no es compatible con el servicio Squoosh por defecto. Consulta la sección de instalación para obtener más detalles sobre cómo usar el servicio sharp en su lugar.

El color de fondo se utiliza para rellenar el fondo restante cuando se utiliza contain para la propiedad fit.

El color de fondo a utilizar para reemplazar el canal alfa con el método flatten de sharp. En caso de que el formato de salida no admita transparencia (p. ej. jpeg), se recomienda incluir un color de fondo; de lo contrario, se utilizará el negro como reemplazo predeterminado para los píxeles transparentes.

El parámetro acepta un valor de tipo string.

El parámetro puede ser un color HTML con nombre, una representación hexadecimal del color con 3 o 6 caracteres hexadecimales en el formato #123[abc], o una definición RGB en el formato rgb(100,100,100), o una definición RGBA en el formato rgba(100,100,100, 0.5).

Tipo: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
Por defecto: 'cover'

Esto no está soportado por el servicio predeterminado de Squoosh. Consulta la sección de instalación para obtener más detalles sobre cómo utilizar el servicio sharp en su lugar. Lee más sobre cómo redimensionar imágenes con sharp.

Cómo debe redimensionarse la imagen para que se ajuste tanto el height como el width.

Tipo: 'top' | 'right top' | 'right' | 'right bottom' | 'bottom' | 'left bottom' | 'left' | 'left top' | 'north' | 'northeast' | 'east' | 'southeast' | 'south' | 'southwest' | 'west' | 'northwest' | 'center' | 'centre' | 'cover' | 'entropy' | 'attention'
Por defecto: 'centre'

Esto no está soportado por el servicio predeterminado de Squoosh. Consulta la sección de instalación para obtener más detalles sobre cómo utilizar el servicio sharp en su lugar. Lee más sobre cómo redimensionar imágenes con sharp.

La posición del recorte cuando el ajuste fit es cover o contain.

El componente integrado <Picture /> se utiliza para crear un elemento <picture /> optimizado tanto para imágenes remotas accedidas por URL como para imágenes locales importadas desde el directorio src/ de tu proyecto.

Además de las propiedades específicas del componente, cualquier atributo HTML válido para el elemento <img /> incluido en el componente <Picture /> será incluido en el elemento <img /> construido.

Tipo: string | ImageMetadata | Promise<ImageMetadata>
Por defecto: true

Fuente del archivo de imagen original.

Para imágenes remotas, proporciona la URL completa. (p. ej. src="https://astro.build/assets/blog/astro-1-release-update.avif")

Para imágenes ubicadas en el directorio src/ de tu proyecto: utiliza la ruta del archivo relativa al directorio src/. (p. ej. src="../assets/source-pic.png")

Para imágenes ubicadas en el directorio public/ de tu proyecto: utiliza la ruta de URL relativa al directorio public/. (p. ej. src="/images/public-image.jpg"). Estas funcionan como imágenes remotas.

Tipo: string
Por defecto: true

Define una descripción de texto alternativa de la imagen.

Establécelo como una cadena vacía (alt="") si la imagen no es una parte clave del contenido (p. ej, si es una decoración o un píxel de seguimiento).

Tipo: string
Por defecto: true

La propiedad sizes del objeto HTMLImageElement te permite especificar el ancho de diseño de la imagen para cada una de las condiciones de los medios en una lista.

Consulta MDN para más detalles.

Tipo: number[]
Por defecto: true

La lista de tamaños que se deben generar para las imágenes responsivas. Esto se combina con aspectRatio para calcular las dimensiones finales de cada imagen generada.

// Genera tres imágenes: una de 400x400, otra de 800x800, y otra de 1200x1200
<Picture src={...} widths={[400, 800, 1200]} aspectRatio="1:1" alt="descriptive text" />

Tipo: number | string
Por defecto: undefined

La relación de aspecto deseada de la imagen de salida. Esto se combina con los widths para calcular las dimensiones finales de cada imagen generada.

Se puede proporcionar un string en la forma de {width}:{height}, por ejemplo: 16:9 o 3:4.

También se puede proporcionar un number, lo cual es útil cuando el aspect ratio se calcula en tiempo de generación. Esto puede ser un número en línea como 1.777 o en línea como una expresión JSX como aspectRatio={16/9}.

Para imágenes remotas, incluyendo imágenes en public/, se requiere aspectRatio para asegurar que el height es correcto se pueda calcular durante la generación.

Tipo: Array<'avif' | 'jpeg' | 'png' | 'webp'>
Por defecto: undefined

Los formatos de salida que se utilizarán en la imagen optimizada. Si no se proporciona ninguno, se utilizarán webp y avif además del formato de imagen original.

Para imágenes remotas, incluidas las imágenes en public/, el formato de imagen original es desconocido. Si no se proporciona, se utilizarán solo webp y avif.

Tipo: ColorDefinition
Por defecto: undefined

Esto no es compatible con el servicio Squoosh por defecto. Consulta la sección de instalación para obtener más detalles sobre cómo usar el servicio sharp en su lugar.

El color de fondo a utilizar para reemplazar el canal alfa con el método flatten de sharp. En caso de que el formato de salida no admita transparencia (p. ej. jpeg), se recomienda incluir un color de fondo; de lo contrario, se utilizará el negro como reemplazo predeterminado para los píxeles transparentes.

El parámetro acepta un valor de tipo string.

El parámetro puede ser un color HTML con nombre, una representación hexadecimal del color con 3 o 6 caracteres hexadecimales en el formato #123[abc], o una definición RGB en el formato rgb(100,100,100).

Tipo: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
Por defecto: 'cover'

Esto no está soportado por el servicio predeterminado de Squoosh. Consulta la sección de instalación para obtener más detalles sobre cómo utilizar el servicio sharp en su lugar. Lee más sobre cómo redimensionar imágenes con sharp.

Cómo la imagen debe ser redimensionada para el height y el width.

Tipo: 'top' | 'right top' | 'right' | 'right bottom' | 'bottom' | 'left bottom' | 'left' | 'left top' | 'north' | 'northeast' | 'east' | 'southeast' | 'south' | 'southwest' | 'west' | 'northwest' | 'center' | 'centre' | 'cover' | 'entropy' | 'attention'
Por defecto: 'centre'

Esto no está soportado por el servicio predeterminado de Squoosh. Consulta la sección de instalación para obtener más detalles sobre cómo utilizar el servicio sharp en su lugar. Lee más sobre cómo redimensionar imágenes con sharp.

La posición del recorte cuando el ajuste fit es cover o contain.

Esta es la función auxiliar utilizada por el componente <Image /> para construir los atributos <img /> para la imagen transformada. Esta función auxiliar se puede utilizar directamente para casos de uso más complejos que no son compatibles actualmente con el componente <Image />.

Esta función auxiliar recibe un objeto con las mismas propiedades que el componente <Image /> y devuelve un objeto con los atributos que deben incluirse en el elemento final <img />.

Esto puede ser útil si necesitas agregar enlaces de precarga a la etiqueta <head> de una página.

---
import { getImage } from '@astrojs/image';

const { src } = await getImage({
    src: import('../assets/hero.png'),
    alt: "My hero image"
  });
---

<html>
  <head>
    <link rel="preload" as="image" href={src} alt="alt text">
  </head>
</html>

Esta es la función auxiliar utilizada por el componente <Picture /> para construir múltiples tamaños y formatos para imágenes responsivas. Esta función auxiliar se puede utilizar directamente para casos de uso más complejos que no son compatibles actualmente con el componente <Picture />.

Esta función auxiliar recibe un objeto con las mismas propiedades que el componente <Picture /> y devuelve un objeto con los atributos que deben incluirse en el elemento final <img /> y auna lista de fuentes que deben utilizarse para renderizar todos los elementos <source> para el elemento <picture>.

La integración se puede configurar para ejecutarse con un servicio de imágenes diferente, ya sea un servicio de imágenes alojado o un transformador de imágenes completo que se ejecuta localmente en tu compilación o implementación de SSR.

Durante el desarrollo, es posible que las imágenes locales aún no se hayan publicado y no estén disponibles para los servicios de imágenes alojados. Las imágenes locales siempre utilizarán el servicio de imágenes incorporado al usar astro dev.

El serviceEntryPoint debe resolver al servicio de imágenes instalado desde NPM. El punto de entrada predeterminado es @astrojs/image/squoosh,que resuelve al punto de entrada exportado desde el package.json de esta integración.

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

export default defineConfig({
  integrations: [image({
    // Ejemplo: El punto de entrada para un servicio de imágenes de terceros instalado desde NPM
    serviceEntryPoint: 'my-image-service/astro.js'
  })],
});

El control logLevel se puede utilizar para controlar la cantidad de detalles que registra la integración durante las compilaciones. Esto puede ser útil para rastrear una imagen o transformación específica que está tardando mucho tiempo en construirse.

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

export default defineConfig({
  integrations: [image({
    // niveles admitidos: 'debug' | 'info' | 'warn' | 'error' | 'silent'
    // por defecto: 'info'
    logLevel: 'debug'
  })],
});

Durante las compilaciones estáticas, la integración almacenará en caché las imágenes transformadas para evitar reconstruir la misma imagen en cada compilación. Esto puede ser especialmente útil si estás utilizando un servicio de alojamiento que te permite almacenar en caché los activos de compilación para implementaciones futuras.

Las imágenes locales se almacenarán en caché durante 1 año y se invalidarán cuando se modifique el archivo de imagen original. Las imágenes remotas se almacenarán en caché en función de las cabeceras de caché de la respuesta de fetch(), de manera similar a cómo un CDN administraría la caché.

De forma predeterminada, las imágenes transformadas se almacenarán en caché en ./node_modules/.astro/image. Esto se puede configurar en las opciones de configuración de la integración.

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

export default defineConfig({
  integrations: [image({
    // puede ser útil si tu proveedor de alojamiento permite el almacenamiento en caché entre las compilaciones de CI.
    cacheDir: "./.cache/image"
  })]
});

El almacenamiento en caché también se puede desactivar utilizando cacheDir: false.

Los archivos de imagen en el directorio src/ de tu proyecto se pueden importar en el frontmatter y pasarse directamente al componente <Image /> como el valor del atributo src=. También se requiere el atributo alt.

Todas las demás propiedades son opcionales y se establecerán en los valores predeterminados del archivo de imagen original si no se proporcionan.

---
import { Image } from '@astrojs/image/components';
import heroImage from '../assets/hero.png';
---

// imagen optimizada, manteniendo el ancho, alto y formato original
<Image src={heroImage} alt="descriptive text" />

// la altura se recalculará para que coincida con la relación de aspecto original
<Image src={heroImage} width={300} alt="descriptive text" />

// recortando a un ancho y alto específicos
<Image src={heroImage} width={300} height={600} alt="descriptive text" />

// recortando a una relación de aspecto específica y convirtiendo a formato avif
<Image src={heroImage} width={300} aspectRatio="16:9" format="avif" alt="descriptive text" />

// las importaciones de imágenes también se pueden incluir directamente en línea
<Image src={import('../assets/hero.png')} alt="descriptive text" />

El componente <Image /> también se puede utilizar con imágenes almacenadas en el directorio public/ y el atributo src= es relativo a la carpeta public. Se tratará como una imagen remota, lo cual requiere proporcionar tanto width y height, o una dimensión y un atributo aspectRatio.

Tu imagen original se copiará sin procesar a la carpeta de compilación, al igual que todos los archivos ubicados en public/, y la integración de imágenes de Astro también devolverá versiones optimizadas de la imagen.

Por ejemplo, utiliza una imagen ubicada en public/social.png en construcciones estáticas o de SSR de la siguiente manera:

---
import { Image } from '@astrojs/image/components';
import socialImage from '/social.png';
---
// En construcciones estáticas: la imagen se compilará y optimizará en `/dist`.
// En construcciones de SSR: el servidor optimizará la imagen cuando sea solicitada por un navegador.
<Image src={socialImage} width={1280} aspectRatio="16:9" alt="descriptive text" />

Las imágenes remotas se pueden transformar con el componente <Image /> component. El componente <Image /> necesita conocer las dimensiones finales para el elemento <img /> para evitar cambios en el diseño del contenido. Para imágenes remotas, esto significa que debes proporcionar width y height, o una de las dimensiones más el aspectRatio requerido.

---
import { Image } from '@astrojs/image/components';

const imageUrl = 'https://astro.build/assets/press/full-logo-dark.png';
---

// Recortando a un ancho y alto específicos
<Image src={imageUrl} width={750} height={250} format="avif" alt="descriptive text" />

// La altura se recalculará para que coincida con el aspect ratio
<Image src={imageUrl} width={750} aspectRatio={16/9} format="avif" alt="descriptive text" />

El componente <Picture /> se puede utilizar para construir automáticamente un elemento <picture> con múltiples tamaños y formatos. Consulta MDN para obtener más información sobre imágenes responsivas y dirección de arte.

Por defecto, la imagen incluirá formatos para avif y webp. Solo para imágenes locales, también se incluirá el formato original de la imagen.

Para imágenes remotas, se requiere un aspectRatio para asegurar que se pueda calcular la altura correcta en el momento de la construcción.

---
import { Picture } from '@astrojs/image/components';
import hero from '../assets/hero.png';

const imageUrl = 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png';
---

// Imagen local con múltiples tamaños
<Picture src={hero} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="descriptive text" />

// Imagen remota (se requiere aspect ratio)
<Picture src={imageUrl} widths={[200, 400, 800]} aspectRatio="4:3" sizes="(max-width: 800px) 100vw, 800px" alt="descriptive text" />

// Las importaciones en línea son compatibles.
<Picture src={import("../assets/hero.png")} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="descriptive text" />

• Si tu instalación no parece funcionar, intenta reiniciar el servidor de desarrollo.
• Si editas y guardas un archivo pero no ves que tu sitio se actualice en consecuencia, intenta refrescar la página.
• Si refrescar la página no actualiza tu vista previa, o si una nueva instalación no parece estar funcionando, entonces reinicia el servidor de desarrollo.

Para obtener ayuda, revisa el canal #support en Discord. ¡Nuestros amigables miembros del Escuadrón de Soporte están aquí para ayudarte!

Puedes revisar nuestra Documentación de Integración de Astro para más información sobre integraciones.

Este paquete es mantenido por el equipo central de Astro. ¡Estás invitado a enviar un problema o PR!

Consulta el CHANGELOG.md para un historial de cambios en esta integración.

Más integraciones