Referencia de la API de Imágenes y Assets

Añadido en: astro@3.0.0

Astro proporciona componentes integrados y funciones helper para optimizar y mostrar tus imágenes. Para características y ejemplos de uso, consulta nuestra guía de imágenes.

Importaciones desde astro:assets

Los siguientes helpers se importan desde el módulo virtual de assets:

import {
  Image,
  Picture,
  Font,
  getImage,
  inferRemoteSize,
  getConfiguredImageService,
  imageConfig,
  fontData,
  experimental_getFontFileURL,
} from 'astro:assets';

<Image />

El componente <Image /> optimiza y transforma imágenes.

src/components/MyComponent.astro

---
// import the Image component and the image
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---

<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt="A description of my image." />

<!-- Output -->
<!-- Image is optimized, proper attributes are enforced -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

El componente <Image /> acepta las siguientes propiedades listadas además de todas las propiedades aceptadas por la etiqueta HTML <img>.

src (obligatorio)

Type: ImageMetadata | string | Promise<{ default: ImageMetadata }>

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 usando 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="descriptive text" />

• Imágenes en la carpeta public/ - usa la ruta del archivo relativa a la carpeta public:

  src/pages/index.astro

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

• Imágenes remotas - usa 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="descriptive text"
    width="200"
    height="150"
  />

alt (obligatorio)

Type: string

Usa el atributo obligatorio alt para proporcionar un string de 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 ignorar la imagen.

width y height (obligatorio para imágenes en public/)

Type: number | `${number}` | undefined

Estas propiedades definen las dimensiones a usar para la imagen.

Cuando se establece un tipo de layout, estos se generan automáticamente basándose en las dimensiones de la imagen y en la mayoría de los casos no deberían establecerse manualmente.

Al usar imágenes en su relación de aspecto original, width y height son opcionales. Estas dimensiones pueden inferirse automáticamente de los archivos de imagen ubicados en src/. Para imágenes remotas, añade el atributo inferSize establecido en true en el componente <Image /> o <Picture /> o usa la función inferRemoteSize().

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

densities

Type: (number | `${number}x`)[] | undefined

Añadido en: astro@3.3.0

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

El atributo densities no es compatible con tener la prop layout o la configuración image.layout establecida, y será ignorado si se establece.

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

Las densidades que son iguales a anchos mayores que la imagen original serán ignoradas 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="A description of my image."
/>

<!-- Output -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 1.5x
    /_astro/my_image.hash.webp 2x
  "
  alt="A description of my image."
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>

widths

Type: number[] | undefined

Añadido en: astro@3.3.0

Una lista de anchos a generar para la imagen.

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

Los atributos widths y sizes se generarán automáticamente para imágenes que usan una propiedad layout. Proporcionar estos valores generalmente no es necesario, pero puede usarse para sobrescribir cualquier valor generado automáticamente.

No proporciones un valor para densities al usar este valor. Solo uno de estos dos valores puede usarse para generar un srcset.

Los anchos que son mayores que la imagen original serán ignorados para evitar el escalado de la imagen.

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image is 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="A description of my image."
/>

<!-- Output -->
<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="A description of my image."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>

sizes

Type: string | undefined

Añadido en: astro@3.3.0

Especifica el ancho del layout de la imagen para cada una de una lista de condiciones de media. Debe proporcionarse al especificar widths.

Los atributos widths y sizes se generarán automáticamente para imágenes que usan una propiedad layout. Proporcionar estos valores generalmente no es necesario, pero puede usarse para sobrescribir cualquier valor generado automáticamente.

El atributo sizes generado para imágenes constrained y full-width se basa en la suposición de que la imagen se muestra cerca del ancho completo de la pantalla cuando el viewport es más pequeño que el ancho de la imagen. Si es significativamente diferente (ej. si está en un layout de múltiples columnas en pantallas pequeñas), puede que necesites ajustar el atributo sizes manualmente para obtener los mejores resultados.

format

Type: ImageOutputFormat | undefined

Puedes especificar opcionalmente el tipo de archivo de imagen de salida a usar.

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

quality

Type: ImageQuality | undefined

quality es una propiedad opcional que puede ser:

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

inferSize

Type: boolean
Default: false

Añadido en: astro@4.4.0

Permite establecer el width y height originales de una imagen remota automáticamente.

Por defecto, este valor está establecido en false y debes especificar manualmente ambas dimensiones para tu imagen remota.

Añade inferSize al componente <Image /> (o inferSize: true a getImage()) para inferir estos valores del contenido de la imagen cuando se obtenga. Esto es útil si no conoces las dimensiones de la imagen remota, o si podrían cambiar:

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="A cat sleeping in the sun." />

A partir de Astro 5.17.3, inferSize solo obtiene dimensiones para dominios de imágenes remotas autorizados. Las imágenes remotas fuera de la lista de permitidos no se obtienen.

priority

Type: boolean
Default: false

Añadido en: astro@5.10.0

Permite establecer automáticamente los atributos loading, decoding y fetchpriority a sus valores óptimos para imágenes above-the-fold.

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} priority alt="A description of my image" />

Cuando se añade priority="true" (o la sintaxis abreviada priority) al componente <Image /> o <Picture />, añadirá los siguientes atributos para indicar al navegador que cargue la imagen inmediatamente:

loading="eager"
decoding="sync"
fetchpriority="high"

Estos atributos individuales aún pueden establecerse manualmente si necesitas personalizarlos más.

layout

Type: 'constrained' | 'full-width' | 'fixed' | 'none'
Default: image.layout | 'none'

Añadido en: astro@5.10.0

Determina cómo la imagen debería redimensionarse cuando su contenedor cambia de tamaño. Puede usarse para sobrescribir el valor configurado por defecto para image.layout.

MyComponent.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="A description of my image." layout='constrained' width={800} height={600} />

Cuando se establece un layout, los atributos srcset y sizes se generan automáticamente basándose en las dimensiones de la imagen y el tipo de layout. El componente <Image /> anterior generará la siguiente salida HTML:

<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="A description of my image"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>

layout soporta los siguientes valores:

• constrained - La imagen se reducirá para ajustarse al contenedor, manteniendo su relación de aspecto, pero no se escalará más allá del width y height especificados, o las dimensiones originales de la imagen.

  Usa esto si quieres que la imagen se muestre al tamaño solicitado cuando sea posible, pero se reduzca para ajustarse a pantallas más pequeñas. Esto coincide con el comportamiento predeterminado para imágenes al usar Tailwind. Si no estás seguro, este es probablemente el layout que deberías elegir.

• full-width - La imagen se escalará para ajustarse al ancho del contenedor, manteniendo su relación de aspecto.

  Usa esto para imágenes hero u otras imágenes que deberían ocupar todo el ancho de la página.

• fixed - La imagen mantendrá las dimensiones solicitadas y no se redimensionará. Generará un srcset para soportar pantallas de alta densidad, pero no para diferentes tamaños de pantalla.

  Usa esto si la imagen no se redimensionará, por ejemplo iconos o logos más pequeños que cualquier ancho de pantalla, u otras imágenes en un contenedor de ancho fijo.

• none - La imagen no será responsive. No se generarán automáticamente srcset ni sizes, y no se aplicarán estilos.

  Esto es útil si has habilitado un layout predeterminado, pero quieres deshabilitarlo para una imagen específica.

Por ejemplo, con constrained establecido como layout predeterminado, puedes sobrescribir la propiedad layout de cualquier imagen individual:

src/components/MyComponent.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="This will use constrained layout" width={800} height={600} />
<Image src={myImage} alt="This will use full-width layout" layout="full-width" />
<Image src={myImage} alt="This will disable responsive images" layout="none" />

El valor de layout también define los estilos predeterminados aplicados a la etiqueta <img> para determinar cómo la imagen debería redimensionarse según su contenedor:

Estilos de imágenes responsivas

:where([data-astro-image]) {
  object-fit: var(--fit);
  object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
  width: 100%;
}
:where([data-astro-image='constrained']) {
  max-width: 100%;
}

fit

Type: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
Default: image.objectFit | 'cover'

Añadido en: astro@5.10.0

Define cómo se debe recortar una imagen si se cambia su relación de aspecto.

Los valores coinciden con los de CSS object-fit. Por defecto es cover, o el valor de image.objectFit si está establecido. Puede usarse para sobrescribir los estilos predeterminados de object-fit.

position

Type: string
Default: image.objectPosition | 'center'

Añadido en: astro@5.10.0

Define la posición del recorte de la imagen si se cambia la relación de aspecto.

Los valores coinciden con los de CSS object-position. Por defecto es center, o el valor de image.objectPosition si está establecido. Puede usarse para sobrescribir los estilos predeterminados de object-position.

background

Type: string | undefined

Añadido en: astro@5.17.0

El color de fondo a usar al aplanar una imagen para transformarla al format de salida solicitado.

Por defecto, Sharp usa un fondo negro al aplanar una imagen. Especificar un color de fondo diferente es especialmente útil al transformar imágenes con fondos transparentes a un formato que no soporta transparencia (ej. .jpeg):

src/components/MyComponent.astro

<Image
  src={myImage}
  alt="A description of my image"
  format="jpeg"
  background="#ffffff"
/>

Los valores se pasan directamente al servicio de imágenes. Sharp acepta cualquier valor que el paquete color-string pueda parsear.

<Picture />

Añadido en: astro@3.3.0

El componente <Picture /> genera una imagen optimizada con múltiples formatos y/o tamaños.

src/pages/index.astro

---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---

<!-- `alt` is mandatory on the Picture component -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />

<!-- Output -->
<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="A description of my image."
  />
</picture>

<Picture /> acepta todas las propiedades de el componente <Image /> más las siguientes:

formats

Type: ImageOutputFormat[]

Un array de formatos de imagen a usar para las etiquetas <source>. Las entradas se añadirán como elementos <source> en el orden en que se listan, y este orden determina qué formato se muestra. Para un mejor rendimiento, lista el formato más moderno primero (ej. webp o avif). Por defecto, esto está establecido en ['webp'].

fallbackFormat

Type: ImageOutputFormat

Formato a usar como valor de fallback para la etiqueta <img>. Por defecto es .png para imágenes estáticas (o .jpg si la imagen es un JPG), .gif para imágenes animadas, y .svg para archivos SVG.

pictureAttributes

Type: HTMLAttributes<'picture'>

Un objeto de atributos a añadir a la etiqueta <picture>.

Usa esta propiedad para aplicar atributos al elemento <picture> externo en sí. Los atributos aplicados directamente al componente <Picture /> se aplicarán al elemento <img> interno, excepto los usados para la transformación de la imagen.

src/components/MyComponent.astro

---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // Image is 1600x900
---

<Picture
  src={myImage}
  alt="A description of my image."
  pictureAttributes={{ style: "background-color: red;" }}
/>

<!-- Output -->
<picture style="background-color: red;">
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    alt="A description of my image."
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>

<Font />

Añadido en: astro@6.0.0

El componente <Font /> genera etiquetas style y puede opcionalmente generar enlaces de precarga para una familia de fuentes dada.

Debe importarse y añadirse al <head> de tu página. Esto se hace comúnmente en un componente como Head.astro que se usa en un layout común del sitio para uso global, pero puede añadirse a páginas individuales según sea necesario.

Con este componente, tienes control sobre qué familia de fuentes se usa en cada página, y qué fuentes se precargan.

src/components/Head.astro

---
import { Font } from "astro:assets";
---

<Font cssVariable="--font-roboto" />

El componente <Font /> acepta las siguientes propiedades:

cssVariable (obligatorio)

Type: CssVariable
Example type: "--font-roboto" | "--font-comic-sans" | ...

El cssVariable registrado en tu configuración de Astro:

src/components/Head.astro

---
import { Font } from "astro:assets";
---

<Font cssVariable="--font-roboto" />

preload

Type: boolean | { weight?: string | number; style?: string; subset?: string }[]
Default: false

Si generar enlaces de precarga o no. Con la directiva preload, el navegador comenzará inmediatamente a descargar todos los enlaces de fuentes posibles durante la carga de la página:

src/components/Head.astro

---
import { Font } from "astro:assets";
---

<Font cssVariable="--font-roboto" preload />

Sé muy intencional sobre qué fuentes precargas. Precargar demasiadas fuentes puede impactar el rendimiento, ya que esto puede bloquear la carga de otros recursos importantes o puede descargar fuentes que no son necesarias para la página actual.

Para controlar selectivamente qué archivos de fuentes se precargan, puedes proporcionar un array de objetos describiendo cualquier combinación de weight, style o subset de la fuente a precargar:

src/components/Head.astro

---
import { Font } from "astro:assets";
---

<Font
  cssVariable="--font-roboto"
  preload={[
    { subset: "latin", style: "normal" },
    { weight: "400" },
  ]}
/>

Los archivos de fuentes de peso variable se precargarán si cualquier peso dentro de su rango es solicitado. Por ejemplo, un archivo de fuente para el peso 100 900 se incluirá cuando se especifica 400 en un objeto preload.

getImage()

Type: (options: UnresolvedImageTransform) => Promise<GetImageResult>

Precaución

getImage() depende de APIs que solo funcionan en el servidor y lanzará un error en el cliente.

Si necesitas la URL de la imagen resultante en el lado del cliente, puedes pasar el src de una llamada a getImage() renderizada en el servidor al cliente.

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

Esto toma un objeto de opciones con las mismas propiedades que el componente Image (excepto alt) y devuelve un objeto GetImageResult.

El siguiente ejemplo genera un background-image AVIF para un <div />:

src/components/Background.astro

---
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});`}><slot /></div>

inferRemoteSize()

Type: (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Añadido en: astro@4.12.0

Una función para establecer el width y height originales de una imagen remota automáticamente. Puede usarse como alternativa a pasar la propiedad inferSize .

import { inferRemoteSize } from 'astro:assets';
const { width, height } = await inferRemoteSize("https://example.com/cat.png");

getConfiguredImageService()

Type: () => Promise<ImageService>

Añadido en: astro@2.1.3

Recupera el servicio de imágenes resuelto.

imageConfig

Type: AstroConfig["image"]

Añadido en: astro@3.0.9

Las opciones de configuración para imágenes establecidas por el usuario y combinadas con todos los valores predeterminados.

fontData

Type: Record<CssVariable, Array<FontData>>

Añadido en: astro@6.0.0

Un objeto donde cada clave es un cssVariable y el valor es un array que describe las fuentes asociadas. Cada fuente es un objeto que contiene un array de src disponibles para esa fuente y las siguientes propiedades opcionales: weight y style:

import { fontData } from "astro:assets"

const data = fontData["--font-roboto"]

experimental_getFontFileURL()

Type: (url: string, requestUrl?: URL) => Promise<string>

Añadido en: astro@6.2.0

Resuelve una URL de archivo de fuente obtenida de fontData:

import { fontData, experimental_getFontFileURL } from "astro:assets";

const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;

if (fontPath === undefined) {
  throw new Error("Cannot find the font path.");
}

const url = experimental_getFontFileURL(fontPath);
const buffer = await fetch(url).then((res) => res.arrayBuffer());

Cuando se llama en una ruta renderizada bajo demanda, necesita proporcionarse la URL de la solicitud:

import type { APIRoute } from "astro";
import { fontData, experimental_getFontFileURL } from "astro:assets"

export const prerender = false; // Not needed in 'server' mode

export const GET: APIRoute = async (context) => {
  // ...
  const url = experimental_getFontFileURL(fontPath, context.url);
  // ...
};

Tipos de astro:assets

Los siguientes tipos se importan desde el módulo virtual de assets:

import type {
  LocalImageProps,
  RemoteImageProps,
  FontData
} from "astro/assets";

LocalImageProps

Tipo: ImageSharedProps<T> & { src: ImageMetadata | Promise<{ default: ImageMetadata; }> }

Describe las propiedades de una imagen local. Esto asegura que src coincida con la estructura de una imagen importada.

Aprende más sobre imágenes importadas en src/ con un ejemplo de uso.

RemoteImageProps

Types:

• ImageSharedProps<T> & { src: string; inferSize: true; }
• ImageSharedProps<T> & { src: string; inferSize?: false | undefined; }

Describe las propiedades de una imagen remota. Esto asegura que cuando inferSize no se proporciona o está establecido en false, tanto width como height son obligatorios.

FontData

Tipo: { src: Array<{ url: string; format?: string; tech?: string }>; weight?: string; style?: string; subset?: string; }

Añadido en: astro@6.0.0

Describe los datos de la fuente asociados con una familia de fuentes dada.

FontData.src

Type: Array<{ url: string; format?: string; tech?: string }>

Un array de objetos que describen los archivos de fuentes disponibles para una familia de fuentes dada. Cada objeto contiene una url y, opcionalmente, el format y tech asociados.

FontData.weight

Type: string

Especifica el peso de la fuente (ej. 400, 600).

FontData.style

Type: string

Especifica el estilo de la fuente (ej. normal, italic).

FontData.subset

Type: string

Añadido en: astro@7.0.0 Nuevo

Especifica el subset de la fuente (ej. latin, cyrillic).

Importaciones desde astro/assets

Los siguientes helpers se importan desde el módulo regular de assets:

import {
  baseService,
  getConfiguredImageService,
  getImage,
  isLocalService,
} from "astro/assets";

baseService

Type: Omit<LocalImageService, ‘transform’>

El servicio de imágenes local integrado que puede extenderse para crear un servicio de imágenes personalizado.

El siguiente ejemplo reutiliza el baseService para crear un nuevo servicio de imágenes:

src/image-service.ts

import { baseService } from "astro/assets";

const newImageService = {
 getURL: baseService.getURL,
 parseURL: baseService.parseURL,
 getHTMLAttributes: baseService.getHTMLAttributes,
 async transform(inputBuffer, transformOptions) {...}
}

getConfiguredImageService()

Ver getConfiguredImageService() desde astro:assets.

getImage()

Type: (options: UnresolvedImageTransform, imageConfig: AstroConfig[‘image’]) => Promise<GetImageResult>

Una función similar a getImage() de astro:assets con dos argumentos obligatorios: un objeto de options con las mismas propiedades que el componente Image y un segundo objeto para la configuración de imágenes.

isLocalService()

Type: (service: ImageService | undefined) => boolean

Verifica el tipo de un servicio de imágenes y devuelve true cuando es un servicio local.

Tipos de astro/assets

Los siguientes tipos se importan desde el módulo regular de assets:

import type {
  LocalImageProps,
  RemoteImageProps,
} from "astro/assets";

LocalImageProps

Ver LocalImageProps desde astro:assets.

RemoteImageProps

Ver RemoteImageProps desde astro:assets.

Importaciones desde astro/assets/utils

Los siguientes helpers se importan desde el directorio utils en el módulo regular de assets y pueden usarse para construir un servicio de imágenes:

import {
  isRemoteAllowed,
  matchHostname,
  matchPathname,
  matchPattern,
  matchPort,
  matchProtocol,
  isESMImportedImage,
  isRemoteImage,
  resolveSrc,
  imageMetadata,
  emitImageMetadata,
  emitClientAsset,
  getOrigQueryParams,
  inferRemoteSize,
  propsToFilename,
  hashTransform,
} from "astro/assets/utils";

isRemoteAllowed()

Tipo: (src: string, { domains, remotePatterns }: { domains: string[], remotePatterns: RemotePattern[] }) => boolean

Añadido en: astro@4.0.0

Determina si un recurso remoto dado, identificado por su URL de origen, está permitido según los dominios especificados y los patrones remotos.

import { isRemoteAllowed } from 'astro/assets/utils';

const url = new URL('https://example.com/images/test.jpg');
const domains = ['example.com', 'anotherdomain.com'];
const remotePatterns = [
  {
    protocol: 'https',
    hostname: 'images.example.com',
    pathname: '/**', // Allow any path under this hostname
  }
];

isRemoteAllowed(url.href, { domains, remotePatterns }); // Output: `true`

matchHostname()

Type: (url: URL, hostname?: string, allowWildcard = false) => boolean

Añadido en: astro@4.0.0

Compara el hostname de una URL dada contra un hostname especificado, con soporte opcional para patrones comodín.

import { matchHostname } from 'astro/assets/utils';

const url = new URL('https://sub.example.com/path/to/resource');

matchHostname(url, 'example.com'); // Output: `false`
matchHostname(url, 'example.com', true); // Output: `true`

matchPathname()

Type: (url: URL, pathname?: string, allowWildcard = false) => boolean

Añadido en: astro@4.0.0

Compara el pathname de una URL dada contra un patrón especificado, con soporte opcional para comodines.

import { matchPathname } from 'astro/assets/utils';

const testURL = new URL('https://example.com/images/photo.jpg');

matchPathname(testURL, '/images/photo.jpg'); // Output: `true`
matchPathname(testURL, '/images/'); // Output: `false`
matchPathname(testURL, '/images/*', true); // Output: `true`

matchPattern()

Type: (url: URL, remotePattern: RemotePattern) => boolean

Añadido en: astro@4.0.0

Evalúa si una URL dada coincide con el patrón remoto especificado según el protocolo, hostname, puerto y pathname.

import { matchPattern } from 'astro/assets/utils';

const url = new URL('https://images.example.com/photos/test.jpg');
const remotePattern = {
  protocol: 'https',
  hostname: 'images.example.com',
  pathname: '/photos/**', // Allow all files under /photos/
};

matchPattern(url, remotePattern); // Output: `true`

matchPort()

Type: (url: URL, port?: string) => boolean
Default: true

Añadido en: astro@4.0.0

Verifica si el puerto de la URL dada coincide con el puerto especificado. Si no se proporciona ningún puerto, devuelve true.

import { matchPort } from 'astro/assets/utils';

const urlWithPort = new URL('https://example.com:8080/resource');
const urlWithoutPort = new URL('https://example.com/resource');

matchPort(urlWithPort, '8080'); // Output: `true`
matchPort(urlWithoutPort, '8080'); // Output: `false`

matchProtocol()

Type: (url: URL, protocol?: string) => boolean
Default: true

Añadido en: astro@4.0.0

Compara el protocolo de la URL proporcionada con un protocolo especificado. Devuelve true si el protocolo coincide o si no se proporciona ningún protocolo.

import { matchProtocol } from 'astro/assets/utils';

const secureUrl = new URL('https://example.com/resource');
const regularUrl = new URL('http://example.com/resource');

matchProtocol(secureUrl, 'https'); // Output: `true`
matchProtocol(regularUrl, 'https'); // Output: `false`

isESMImportedImage()

Type: (src: ImageMetadata | string) => boolean

Añadido en: astro@4.0.0

Determina si la fuente dada es una imagen importada como módulo ECMAScript (ESM).

import { isESMImportedImage } from 'astro/assets/utils';

const imageMetadata = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};
const filePath = '/images/photo.jpg';

isESMImportedImage(imageMetadata); // Output: `true`
isESMImportedImage(filePath); // Output: `false`

isRemoteImage()

Type: (src: ImageMetadata | string) => boolean

Añadido en: astro@4.0.0

Determina si la fuente proporcionada es una URL de imagen remota en forma de string.

import { isRemoteImage } from 'astro/assets/utils';

const imageUrl = 'https://example.com/images/photo.jpg';
const localImage = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};

isRemoteImage(imageUrl); // Output: `true`
isRemoteImage(localImage); // Output: `false`

resolveSrc()

Type: (src: UnresolvedImageTransform[‘src’]) => Promise<string | ImageMetadata>

Añadido en: astro@4.0.0

Devuelve la fuente de la imagen. Esta función asegura que si src es una Promise (ej., un import() dinámico), se espera y se extrae el src correcto. Si src ya es un valor resuelto, se devuelve tal cual.

import { resolveSrc } from 'astro/assets/utils';
import localImage from "./images/photo.jpg";

const resolvedLocal = await resolveSrc(localImage);
// Example value: `{ src: '/@fs/home/username/dev/astro-project/src/images/photo.jpg', width: 800, height: 600, format: 'jpg' }`

const resolvedRemote = await resolveSrc("https://example.com/remote-img.jpg");
// Value: `"https://example.com/remote-img.jpg"`

const resolvedDynamic = await resolveSrc(import("./images/dynamic-image.jpg"))
// Example value: `{ src: '/@fs/home/username/dev/astro-project/src/images/dynamic-image.jpg', width: 800, height: 600, format: 'jpg' }`

imageMetadata()

Tipo: (data: Uint8Array, src?: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Añadido en: astro@4.0.0

Extrae metadatos de la imagen como dimensiones, formato y orientación de los datos de imagen proporcionados.

import { imageMetadata } from 'astro/assets/utils';

const binaryImage = new Uint8Array([/* ...binary image data... */]);
const sourcePath = '/images/photo.jpg';

const metadata = await imageMetadata(binaryImage, sourcePath);
// Example value:
// {
//    width: 800,
//    height: 600,
//    format: 'jpg',
//    orientation: undefined
// }

emitImageMetadata()

Tipo: (id: string | undefined, fileEmitter?: Rollup.EmitFile) => Promise<(ImageMetadata & { contents?: Buffer }) | undefined>

Añadido en: astro@5.7.0

Procesa un archivo de imagen y emite sus metadatos y opcionalmente sus contenidos. En modo build, la función usa fileEmitter para generar una referencia de asset. En modo desarrollo, resuelve a una URL de archivo local con parámetros de consulta para los metadatos.

import { emitImageMetadata } from 'astro/assets/utils';

const imageId = '/images/photo.jpg';
const metadata = await emitImageMetadata(imageId);
// Example value:
// {
//    src: '/@fs/home/username/dev/astro-project/src/images/photo.jpg?origWidth=800&origHeight=600&origFormat=jpg',
//    width: 800,
//    height: 600,
//    format: 'jpg',
//    contents: Uint8Array([...])
// }

emitClientAsset()

Type: (pluginContext: Rollup.PluginContext, options: Rollup.EmitFile) => string

Añadido en: astro@6.0.0

Emite un asset de cliente que será movido al directorio de cliente para assets (ej. dist/client/_astro/) durante los builds SSR. Esta función está pensada para autores de integraciones que necesitan emitir assets (como imágenes) desde contenido renderizado en el servidor que debería estar disponible en el cliente.

Usa esto en lugar de Rollup pluginContext.emitFile() directamente cuando trabajes en un contexto de plugin de Vite y necesites que el asset emitido sea movido al directorio de salida del cliente.

import { emitClientAsset } from 'astro/assets/utils';

function myVitePlugin() {
  return {
    name: 'my-plugin',
    transform(code, id) {
      const handle = emitClientAsset(this, {
        type: 'asset',
        name: 'my-image.png',
        source: imageBuffer,
      });
      // Returns the asset handle similar to `emitFile()`
    }
  }
}

getOrigQueryParams()

Tipo: (params: URLSearchParams) => Pick<ImageMetadata, ‘width’ | ‘height’ | ‘format’> | undefined

Añadido en: astro@4.0.0

Recupera el width, height y format de una imagen desde un objeto URLSearchParams. Si cualquiera de estos parámetros falta o es inválido, la función devuelve undefined.

import { getOrigQueryParams } from 'astro/assets/utils';

const url = new URL('https://example.com/image.jpg?width=800&height=600&format=jpg');
const origParams = getOrigQueryParams(url.searchParams);
// Example value:
// {
//    width: 800,
//    height: 600,
//    format: 'jpg'
// }

inferRemoteSize()

Type: (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Añadido en: astro@4.0.0

Infiere las dimensiones de una imagen remota transmitiendo sus datos y analizándolos progresivamente hasta que haya suficiente metadata disponible.

import { inferRemoteSize } from 'astro/assets/utils';

const remoteImageUrl = 'https://example.com/image.jpg';
const imageSize = await inferRemoteSize(remoteImageUrl);
// Example value:
// {
//    width: 1920,
//    height: 1080,
//    format: 'jpg'
// }

propsToFilename()

Type: (filePath: string, transform: ImageTransform, hash: string) => string

Añadido en: astro@4.0.0

Genera un nombre de archivo formateado para una imagen basado en su ruta de origen, propiedades de transformación y un hash único.

El nombre de archivo formateado sigue esta estructura:

<prefixDirname>/<baseFilename>_<hash><outputExtension>

• prefixDirname: Si la imagen es una imagen importada como ESM, este es el nombre del directorio de la ruta del archivo original; de lo contrario, será un string vacío.
• baseFilename: El nombre base del archivo o un nombre corto hasheado si el archivo es una URI data:.
• hash: Un string hash único generado para distinguir el archivo transformado.
• outputExtension: La extensión de archivo de salida deseada derivada del transform.format o la extensión del archivo original.

import { propsToFilename } from 'astro/assets/utils';

const filePath = '/images/photo.jpg';
const transform = { format: 'png', src: filePath };
const hash = 'abcd1234';

const filename = propsToFilename(filePath, transform, hash);
// Example value: '/images/photo_abcd1234.png'

hashTransform()

Tipo: (transform: ImageTransform, imageService: string, propertiesToHash: string[]) => string

Añadido en: astro@4.0.0

Transforma el objeto transform proporcionado en un string hash basándose en propiedades seleccionadas y el imageService especificado.

import { hashTransform } from 'astro/assets/utils';

const transform = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};
const imageService = 'astro/assets/services/sharp';
const propertiesToHash = ['width', 'height', 'format'];

const hash = hashTransform(transform, imageService, propertiesToHash);
// Example value: 'd41d8cd98f00b204e9800998ecf8427e'

Tipos de astro

import type {
  GetImageResult,
  ImageTransform,
  UnresolvedImageTransform,
  ImageMetadata,
  ImageInputFormat,
  ImageOutputFormat,
  ImageQuality,
  ImageQualityPreset,
  RemotePattern,
  ImageService,
  ExternalImageService,
  LocalImageService,
  ImageServiceConfig,
} from "astro";

GetImageResult

Type: object

Añadido en: astro@2.2.0

Describe el resultado de la transformación después de la llamada a getImage().

GetImageResult.attributes

Type: Record<string, any>

Define los atributos HTML adicionales necesarios para renderizar la imagen (ej. width, height, style).

GetImageResult.options

Type: ImageTransform

Describe los ajustes de transformación después de la validación.

GetImageResult.rawOptions

Type: ImageTransform

Describe los ajustes de transformación originales.

GetImageResult.src

Type: string

La ruta a la imagen generada.

GetImageResult.srcSet

Tipo: { values: { transform: ImageTransform; descriptor?: string; attributes?: Record<string, any>; url: string; }[]; attribute: string; }

Añadido en: astro@3.3.0

Un objeto que describe cómo renderizar el atributo srcset.

GetImageResult.srcSet.values

Tipo: { transform: ImageTransform; descriptor?: string; attributes?: Record<string, any>; url: string; }[]

Un array de valores generados donde cada entrada incluye una URL y un descriptor de tamaño. Esto puede usarse para generar manualmente el valor del atributo srcset.

GetImageResult.srcSet.attribute

Type: string

Un valor listo para usar en el atributo srcset.

ImageTransform

Type: object

Define las opciones aceptadas por el servicio de transformación de imágenes. Esto contiene una propiedad src obligatoria, propiedades predefinidas opcionales, y cualquier propiedad adicional requerida por el servicio de imágenes:

ImageTransform.src

Type: ImageMetadata | string

Define la ruta a una imagen local en el directorio public, la URL de una imagen remota, o los datos de una imagen importada.

ImageTransform.width

Type: number | undefined

El ancho de la imagen.

ImageTransform.height

Type: number | undefined

La altura de la imagen.

ImageTransform.widths

Type: number[] | undefined

Añadido en: astro@3.3.0

Una lista de anchos a generar para la imagen.

ImageTransform.densities

Type: (number | `${number}x`)[] | undefined

Añadido en: astro@3.3.0

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

ImageTransform.quality

Type: ImageQuality | undefined

La calidad deseada para la imagen de salida.

ImageTransform.format

Type: ImageOutputFormat | undefined

El formato deseado para la imagen de salida.

ImageTransform.fit

Tipo: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | string | undefined

Añadido en: astro@5.0.0

Define una lista de valores permitidos para la propiedad CSS object-fit, extensible con cualquier string.

ImageTransform.position

Type: string | undefined

Añadido en: astro@5.0.0

Controla el valor para la propiedad CSS object-position.

UnresolvedImageTransform

Tipo: Omit<ImageTransform, “src”> & { src: ImageMetadata | string | Promise<{ default: ImageMetadata }>; inferSize?: boolean; }

Representa una imagen con opciones de transformación. Esto contiene las mismas propiedades que el tipo ImageTransform con un tipo de src diferente y una propiedad inferSize adicional.

UnresolvedImageTransform.src

Type: ImageMetadata | string | Promise<{ default: ImageMetadata }>

La ruta a una imagen importada o ubicada en el directorio public, o la URL de una imagen remota.

UnresolvedImageTransform.inferSize

Type: boolean

Determina si el ancho y la altura de la imagen deben inferirse.

Ver también el atributo inferSize disponible en <Image />.

ImageMetadata

Tipo: { src: string; width: number; height: number; format: ImageInputFormat; orientation?: number; }

Añadido en: astro@2.1.3

Describe los datos recopilados durante la importación de la imagen. Esto contiene las siguientes propiedades:

ImageMetadata.src

Type: string

La ruta absoluta de la imagen en el sistema de archivos.

ImageMetadata.width

Type: number

El ancho de la imagen.

ImageMetadata.height

Type: number

La altura de la imagen.

ImageMetadata.format

Type: ImageInputFormat

El formato de la imagen.

ImageMetadata.orientation

Type: number

Añadido en: astro@2.8.3

La orientación de la imagen cuando sus metadatos contienen esta información.

ImageInputFormat

Type: "jpeg" | "jpg" | "png" | "tiff" | "webp" | "gif" | "svg" | "avif"

Añadido en: astro@2.2.0

Describe una unión de formatos soportados para imágenes importadas.

ImageOutputFormat

Type: string | "jpeg" | "jpg" | "png" | "webp" | "svg" | "avif"

Añadido en: astro@2.2.0

Especifica el formato para las imágenes de salida. Puede ser un literal predefinido o cualquier string.

ImageQuality

Type: ImageQualityPreset | number

Añadido en: astro@2.2.0

Representa la calidad perceptual de la imagen de salida como una unión de literales predefinidos, un string o un número.

ImageQualityPreset

Type: string | "low" | "mid" | "high" | "max"

Añadido en: astro@2.2.0

Define los presets disponibles para controlar la calidad de la imagen, extensible con cualquier string.

RemotePattern

Tipo: { hostname?: string; pathname?: string; protocol?: string; port?: string; }

Añadido en: astro@5.14.2

Describe un host remoto a través de cuatro propiedades opcionales: hostname, pathname, protocol y port.

ImageService

Type: ExternalImageService | LocalImageService

Define los hooks que un servicio de imágenes local o externo debe proporcionar.

ExternalImageService

Type: object

Define los hooks que un servicio externo de transformación de imágenes debe proporcionar. Esto requiere un hook getUrl() y soporta tres hooks adicionales.

Aprende cómo construir servicios externos en la referencia de la API del Servicio de Imágenes con un ejemplo de uso.

LocalImageService

Type: object

Define los hooks que un servicio local de transformación de imágenes debe proporcionar. Esto requiere los hooks getUrl(), parseUrl() y transform(), y soporta hooks adicionales.

Aprende cómo construir servicios locales en la referencia de la API del Servicio de Imágenes con un ejemplo de uso.

ImageServiceConfig

Tipo: { entrypoint: 'astro/assets/services/sharp' | string; config?: T; }

Añadido en: astro@2.3.3

Describe el objeto de configuración para un servicio de imágenes. Esto contiene las siguientes propiedades:

ImageServiceConfig.entrypoint

Type: 'astro/assets/services/sharp' | string

Un paquete o ruta al módulo del servicio de imágenes. Puede ser el servicio Sharp integrado de Astro o un servicio de terceros.

ImageServiceConfig.config

Type: Record<string, any>

Un objeto de configuración pasado al servicio de imágenes. La estructura depende del servicio específico que se esté usando.