Optimización de imágenes

Según el Web Almanac, las imágenes representan una gran parte del peso de página típico de un sitio web y pueden tener un impacto considerable en el rendimiento LCP de tu sitio.

El componente Image de Next.js extiende el elemento HTML <img> con funciones para la optimización automática de imágenes:

• Optimización de tamaño: Sirve automáticamente imágenes del tamaño correcto para cada dispositivo, usando formatos modernos como WebP y AVIF.
• Estabilidad visual: Previene automáticamente el desplazamiento de diseño mientras las imágenes se cargan.
• Carga más rápida: Las imágenes solo se cargan cuando entran en el viewport usando la carga diferida nativa del navegador, con placeholders opcionales de desenfoque.
• Flexibilidad de activos: Redimensionamiento de imágenes bajo demanda, incluso para imágenes almacenadas en servidores remotos.

🎥 Mira: Aprende más sobre cómo usar next/image → YouTube (9 minutos).

Uso

import Image from 'next/image'

Luego puedes definir el src para tu imagen (ya sea local o remota).

Imágenes locales

Para usar una imagen local, importa tus archivos de imagen .jpg, .png o .webp.

Next.js determinará automáticamente el width y height de tu imagen basándose en el archivo importado. Estos valores se usan para prevenir Cambio Acumulativo de Diseño (CLS) mientras tu imagen se carga.

import Image from 'next/image'
import profilePic from './me.png'

export default function Page() {
  return (
    <Image
      src={profilePic}
      alt="Foto del autor"
      // width={500} proporcionado automáticamente
      // height={500} proporcionado automáticamente
      // blurDataURL="data:..." proporcionado automáticamente
      // placeholder="blur" // Opcional: efecto de desenfoque durante la carga
    />
  )
}

Advertencia: No se admiten await import() dinámicos ni require(). El import debe ser estático para que pueda analizarse en tiempo de compilación.

Puedes configurar opcionalmente localPatterns en tu archivo next.config.js para permitir imágenes específicas y bloquear todas las demás.

module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/images/**',
        search: '',
      },
    ],
  },
}

Imágenes remotas

Para usar una imagen remota, la propiedad src debe ser una cadena URL.

Como Next.js no tiene acceso a archivos remotos durante el proceso de compilación, deberás proporcionar manualmente las propiedades width, height y opcionalmente blurDataURL.

Los atributos width y height se usan para inferir la relación de aspecto correcta de la imagen y evitar cambios de diseño mientras la imagen se carga. El width y height no determinan el tamaño renderizado del archivo de imagen. Aprende más sobre Dimensionamiento de imágenes.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="https://s3.amazonaws.com/my-bucket/profile.png"
      alt="Foto del autor"
      width={500}
      height={500}
    />
  )
}

Para permitir de forma segura la optimización de imágenes, define una lista de patrones URL admitidos en next.config.js. Sé lo más específico posible para evitar usos maliciosos. Por ejemplo, la siguiente configuración solo permitirá imágenes de un bucket específico de AWS S3:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.amazonaws.com',
        port: '',
        pathname: '/my-bucket/**',
        search: '',
      },
    ],
  },
}

Aprende más sobre la configuración de remotePatterns. Si deseas usar URLs relativas para el src de la imagen, usa un loader.

Dominios

A veces puedes querer optimizar una imagen remota, pero seguir usando la API de Optimización de Imágenes integrada de Next.js. Para hacer esto, deja el loader en su configuración predeterminada e ingresa una URL absoluta para la propiedad src de Image.

Para proteger tu aplicación de usuarios maliciosos, debes definir una lista de nombres de host remotos que pretendas usar con el componente next/image.

Aprende más sobre la configuración de remotePatterns.

Loaders

Nota que en el ejemplo anterior, se proporciona una URL parcial ("/me.png") para una imagen local. Esto es posible gracias a la arquitectura de loaders.

Un loader es una función que genera las URLs para tu imagen. Modifica el src proporcionado y genera múltiples URLs para solicitar la imagen en diferentes tamaños. Estas múltiples URLs se usan en la generación automática de srcset, para que los visitantes de tu sitio reciban una imagen del tamaño correcto para su viewport.

El loader predeterminado para aplicaciones Next.js usa la API de Optimización de Imágenes integrada, que optimiza imágenes desde cualquier lugar de la web y luego las sirve directamente desde el servidor web de Next.js. Si deseas servir tus imágenes directamente desde un CDN o servidor de imágenes, puedes escribir tu propia función loader con unas pocas líneas de JavaScript.

Puedes definir un loader por imagen con la propiedad loader, o a nivel de aplicación con la configuración loaderFile.

Prioridad

Debes agregar la propiedad priority a la imagen que será el elemento Largest Contentful Paint (LCP) para cada página. Esto permite a Next.js priorizar especialmente la imagen para su carga (por ejemplo, mediante etiquetas de precarga o hints de prioridad), lo que genera una mejora significativa en LCP.

El elemento LCP suele ser la imagen más grande o el bloque de texto visible dentro del viewport de la página. Cuando ejecutas next dev, verás una advertencia en la consola si el elemento LCP es un <Image> sin la propiedad priority.

Una vez que hayas identificado la imagen LCP, puedes agregar la propiedad así:

import Image from 'next/image'
import profilePic from '../public/me.png'

export default function Page() {
  return <Image src={profilePic} alt="Foto del autor" priority />
}

Consulta más sobre prioridad en la documentación del componente next/image.

Dimensionamiento de imágenes

Una de las formas más comunes en que las imágenes afectan el rendimiento es a través del desplazamiento de diseño, donde la imagen empuja otros elementos de la página mientras se carga. Este problema de rendimiento es tan molesto para los usuarios que tiene su propio Core Web Vital, llamado Cambio Acumulativo de Diseño (CLS). La forma de evitar desplazamientos de diseño basados en imágenes es siempre dimensionar tus imágenes. Esto permite al navegador reservar exactamente el espacio necesario para la imagen antes de que se cargue.

Como next/image está diseñado para garantizar buenos resultados de rendimiento, no se puede usar de una manera que contribuya al desplazamiento de diseño, y debe dimensionarse de una de estas tres formas:

1. Automáticamente, usando una importación estática
2. Explícitamente, incluyendo una propiedad width y height
3. Implícitamente, usando fill que hace que la imagen se expanda para llenar su elemento padre.

¿Qué pasa si no conozco el tamaño de mis imágenes?

Si accedes a imágenes desde una fuente sin conocimiento de sus tamaños, hay varias cosas que puedes hacer:

Usa fill

La propiedad fill permite que tu imagen se dimensione por su elemento padre. Considera usar CSS para dar espacio al elemento padre de la imagen en la página junto con la propiedad sizes para que coincida con cualquier punto de interrupción de media query. También puedes usar object-fit con fill, contain o cover, y object-position para definir cómo debe ocupar ese espacio la imagen.

Normaliza tus imágenes

Si sirves imágenes desde una fuente que controlas, considera modificar tu pipeline de imágenes para normalizarlas a un tamaño específico.

Modifica tus llamadas API

Si tu aplicación recupera URLs de imágenes mediante una llamada API (como a un CMS), puedes modificar la llamada API para devolver las dimensiones junto con la URL.

Si ninguno de los métodos sugeridos funciona para dimensionar tus imágenes, el componente next/image está diseñado para funcionar bien en una página junto con elementos <img> estándar.

Estilización

Estilizar el componente Image es similar a estilizar un elemento <img> normal, pero hay algunas pautas a tener en cuenta:

• Usa className o style, no styled-jsx.
  • En la mayoría de los casos, recomendamos usar la propiedad className. Esto puede ser un CSS Module importado, una hoja de estilos global, etc.
  • También puedes usar la propiedad style para asignar estilos en línea.
  • No puedes usar styled-jsx porque está limitado al componente actual (a menos que marques el estilo como global).
• Cuando uses fill, el elemento padre debe tener position: relative
  • Esto es necesario para el renderizado adecuado del elemento de imagen en ese modo de diseño.
• Cuando uses fill, el elemento padre debe tener display: block
  • Esto es lo predeterminado para elementos <div>, pero debe especificarse en otros casos.

Ejemplos

Responsive

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Responsive() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column' }}>
      <Image
        alt="Montañas"
        // Importar una imagen establecerá
        // automáticamente el ancho y alto
        src={mountains}
        sizes="100vw"
        // Hacer que la imagen muestre el ancho completo
        style={{
          width: '100%',
          height: 'auto',
        }}
      />
    </div>
  )
}

Llenar contenedor

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Fill() {
  return (
    <div
      style={{
        display: 'grid',
        gridGap: '8px',
        gridTemplateColumns: 'repeat(auto-fit, minmax(400px, auto))',
      }}
    >
      <div style={{ position: 'relative', height: '400px' }}>
        <Image
          alt="Montañas"
          src={mountains}
          fill
          sizes="(min-width: 808px) 50vw, 100vw"
          style={{
            objectFit: 'cover', // cover, contain, none
          }}
        />
      </div>
      {/* Y más imágenes en la cuadrícula... */}
    </div>
  )
}

Imagen de fondo

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Background() {
  return (
    <Image
      alt="Montañas"
      src={mountains}
      placeholder="blur"
      quality={100}
      fill
      sizes="100vw"
      style={{
        objectFit: 'cover',
      }}
    />
  )
}

Para ejemplos del componente Image usado con varios estilos, consulta la Demostración del Componente de Imagen.

Otras propiedades

Ver todas las propiedades disponibles para el componente next/image.

Configuración

El componente next/image y la API de Optimización de Imágenes de Next.js se pueden configurar en el archivo next.config.js. Estas configuraciones te permiten habilitar imágenes remotas, definir breakpoints de imagen personalizados, cambiar el comportamiento de caché y más.

Lee la documentación completa de configuración de imágenes para más información.