Lazy loading de imágenes con Claude Code: guía segura para principiantes

El lazy loading de imágenes no consiste en añadir loading="lazy" a todas las etiquetasimg. Si Claude Code retrasa también la imagen hero, el Largest Contentful Paint, es decir, el momento en que aparece el contenido principal visible, puede empeorar. Si carga por adelantado todas las miniaturas de producto, galería y artículos relacionados, el lector móvil descarga imágenes que quizá nunca vea.

Esta guía reconstruye el patrón seguro para principiantes: lazy loading nativo, hero o LCP en eager, decoding, fetchpriority, dimensiones para evitar CLS, srcset y sizes, IntersectionObserver para casos avanzados, placeholders, errores de SEO y UX, medición y prompts seguros para Claude Code. Verifiqué la base técnica con la referencia de MDN delelemento img, Intersection Observer API, web.dev sobrelazy loading nativo de imágenes, Core Web Vitals y la guía de Chrome sobreLCP request discovery.

Para una estrategia más amplia, combina este artículo conoptimización de imágenes, skeleton loading yoptimización de rendimiento.

La regla principal

La regla es sencilla: no retrases la imagen que el usuario ve al abrir la página. Usa lazy loading para imágenes bajo el primer viewport y reserva espacio para todas conwidth yheight, o con unaspect-ratio equivalente.

Ubicación	loading	fetchpriority	decoding	Protección necesaria
Hero o candidata LCP	eager u omitido	Considera high	sync o async	Debe descubrirse desde el HTML inicial
Diagrama a mitad del artículo	lazy	auto	async	Mantener dimensiones
Grid de productos después de la primera pantalla	lazy	auto	async	Usar srcset y sizes
Carrusel o scroll infinito	Depende	auto	async	IntersectionObserver si hace falta

El error habitual es pensar que “imagen pesada” significa “imagen lazy”. La pregunta correcta es si esa imagen participa en la primera vista útil. La documentación de Chrome para LCP recomienda que la imagen LCP sea fácil de descubrir, tenga prioridad adecuada y no useloading=lazy.

HTML listo para copiar

La primera imagen es hero, por eso usa eager y prioridad alta. La segunda aparece más abajo en el artículo o en una lista, por eso usa lazy nativo y decodificación asíncrona.

<img
  class="hero-image"
  src="/images/hero/product-dashboard-1200.webp"
  srcset="
    /images/hero/product-dashboard-640.webp 640w,
    /images/hero/product-dashboard-1200.webp 1200w
  "
  sizes="100vw"
  alt="Primera vista de un panel de producto"
  width="1200"
  height="675"
  loading="eager"
  fetchpriority="high"
  decoding="sync"
/>

<img
  class="article-image"
  src="/images/articles/setup-step-800.webp"
  srcset="
    /images/articles/setup-step-400.webp 400w,
    /images/articles/setup-step-800.webp 800w
  "
  sizes="(max-width: 720px) 100vw, 720px"
  alt="Captura de pantalla del paso de configuración"
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>

decoding="async" es una pista para que el navegador pueda decodificar la imagen sin bloquear tanto otras tareas de renderizado. Es un buen valor para imágenes de contenido y miniaturas. En la hero conviene medirsync frente aasync, no elegir por costumbre.

Evitar CLS con CSS

CLS significa Cumulative Layout Shift. En términos simples, mide cuánto salta la página mientras el usuario intenta leer o tocar. Si una imagen aparece sin altura reservada, mueve texto, anuncios, formularios y CTAs. Eso afecta conversión, no solo una puntuación de Lighthouse.

.image-frame {
  aspect-ratio: 16 / 9;
  background: #f3f4f6;
  overflow: hidden;
}

.image-frame > img {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
}

@media (prefers-reduced-motion: no-preference) {
  .image-frame > img {
    transition: opacity 180ms ease-out;
  }
}

Si tu CMS conoce el ancho y alto de la imagen original, guárdalos y pásalos a la plantilla. Si la imagen viene de un tercero y no conoces su tamaño, reserva un contenedor estable conaspect-ratio y encaja la imagen conobject-fit.

Componente React pequeño

Cuando pidas a Claude Code cambios en React, encierra la política en un componente. Así las imágenes prioritarias son eager, las de contenido son lazy y todas conservan dimensiones.

type SmartImageProps = {
  src: string;
  srcSet?: string;
  sizes?: string;
  alt: string;
  width: number;
  height: number;
  priority?: boolean;
  className?: string;
};

export function SmartImage({
  src,
  srcSet,
  sizes,
  alt,
  width,
  height,
  priority = false,
  className,
}: SmartImageProps) {
  const loading = priority ? "eager" : "lazy";
  const fetchPriority = priority ? "high" : "auto";
  const decoding = priority ? "sync" : "async";

  return (
    <span
      className={`image-frame ${className ?? ""}`}
      style={{ aspectRatio: `${width} / ${height}` }}
    >
      <img
        src={src}
        srcSet={srcSet}
        sizes={sizes}
        alt={alt}
        width={width}
        height={height}
        loading={loading}
        fetchPriority={fetchPriority}
        decoding={decoding}
      />
    </span>
  );
}

El componente es deliberadamente simple. No oculta imágenes importantes detrás de JavaScript ni fuerza una nueva infraestructura. Puedes adaptar la misma regla a Next.js, Astro o componentes de CMS.

Casos de uso reales

El primer caso es una grilla ecommerce. Los primeros productos pueden estar en la primera pantalla, así que no marques todo como lazy. Las recomendaciones, reseñas, historial y productos de la segunda pantalla sí son buenos candidatos. Un fallo concreto es ponerfetchpriority="high" en todas las miniaturas; el navegador deja de distinguir lo urgente.

El segundo caso es un tutorial o artículo editorial. La portada suele ser candidata LCP y debe ser eager. Las capturas de pasos, diagramas después de bloques de código y tarjetas relacionadas pueden ser lazy. Un fallo concreto es usar un placeholder borroso como fondo y dejar elalt real vacío. Si la imagen comunica algo, SEO y lectores de pantalla necesitan texto.

El tercer caso es un dashboard SaaS. Avatares, logos de clientes, miniaturas de reportes y capturas de auditoría pueden aparecer en listas largas. Lazy loading ayuda en filas fuera de pantalla, pero no retrases el gráfico superior ni la imagen que acompaña el CTA inicial. Para medir eventos de CTA y monetización, conecta esto conimplementación de analytics.

También está el caso de galerías y carruseles horizontales. El lazy nativo suele bastar, pero IntersectionObserver ayuda cuando hay contenedores con scroll propio, slides ocultos o una distancia de precarga personalizada.

Cuándo usar IntersectionObserver

Empieza con lazy nativo. Usa IntersectionObserver cuando necesites cargar 300px antes, cambiardata-src, quitar clases de placeholder o observar un contenedor de scroll específico.

<img
  class="js-lazy-image"
  src="/images/placeholders/report-thumb.svg"
  data-src="/images/reports/report-2026.webp"
  data-srcset="/images/reports/report-2026.webp 1x"
  alt="Miniatura del informe mensual"
  width="640"
  height="360"
/>

const lazyImages = document.querySelectorAll("img[data-src]");

function loadImage(img) {
  img.src = img.dataset.src;

  if (img.dataset.srcset) {
    img.srcset = img.dataset.srcset;
  }

  img.removeAttribute("data-src");
  img.removeAttribute("data-srcset");
}

if ("IntersectionObserver" in window) {
  const observer = new IntersectionObserver((entries, currentObserver) => {
    entries.forEach((entry) => {
      if (!entry.isIntersecting) return;

      loadImage(entry.target);
      currentObserver.unobserve(entry.target);
    });
  }, {
    rootMargin: "300px 0px",
    threshold: 0.01,
  });

  lazyImages.forEach((image) => observer.observe(image));
} else {
  lazyImages.forEach(loadImage);
}

Mantén las dimensiones también en esta ruta. Una imagen condata-src puede no cargarse si falla JavaScript, así que no uses este patrón para la imagen principal del producto ni para la hero del artículo.

Medición

Core Web Vitals se centra en LCP, INP y CLS. Los umbrales buenos habituales son LCP en 2,5 segundos o menos, INP en 200 ms o menos y CLS en 0,1 o menos. En lazy loading de imágenes, LCP y CLS son los indicadores más sensibles.

npm install web-vitals

import { onCLS, onINP, onLCP } from "web-vitals";

onLCP((metric) => {
  const lastEntry = metric.entries.at(-1);
  console.log("LCP", metric.value, lastEntry?.element);
});

onCLS((metric) => {
  console.log("CLS", metric.value, metric.entries);
});

onINP((metric) => {
  console.log("INP", metric.value, metric.entries);
});

En Chrome DevTools revisa si el elemento LCP es la hero esperada, si la petición se descubre desde el HTML y si alguna imagen provoca layout shift. Después de publicar, compara PageSpeed Insights, Search Console y tus propios eventos.

Prompt seguro para Claude Code

Claude Code puede hacer reemplazos amplios. Dale alcance, reglas y verificación antes de tocar archivos.

{
  "goal": "Añadir lazy loading seguro a las imágenes",
  "scope": [
    "Solo imágenes de cuerpo de artículo y listas de productos",
    "No aplicar lazy a imágenes de primera pantalla o candidatas LCP"
  ],
  "rules": [
    "Conservar alt, width y height en cada img",
    "Usar loading=\"lazy\" y decoding=\"async\" bajo el fold",
    "Usar loading=\"eager\" u omitir loading en hero",
    "Usar fetchpriority=\"high\" como máximo en una candidata LCP"
  ],
  "verification": [
    "Comprobar MDX y code fences",
    "Revisar LCP y CLS en DevTools",
    "Verificar en móvil que imagen, texto y CTA no se solapan"
  ]
}

Pide además que informe qué imágenes no cambió a lazy y por qué. Esa explicación protege la revisión.

Lista de fallos

• La hero, la imagen principal de producto o el fondo del CTA superior quedó lazy.
• Se eliminaronwidth yheight.
• Todas las imágenes recibieronfetchpriority="high".
• Las variantes desrcset tienen proporciones distintas sin art direction.
• Se intentó aplicarloading a una imagen de fondo CSS.
• Diagramas con significado quedaron conalt vacío.
• Imágenes importantes dependen solo de JavaScript.
• El placeholder domina visualmente más que el contenido real.

CTA y nota de prueba

El lazy loading de imágenes no es solo una mejora de puntuación. Afecta lectura, visibilidad de CTA, exploración de productos y primera acción dentro de una app. Para trabajo individual, empieza con lachuleta gratuita de Claude Code. Para prompts y plantillas reutilizables, mira lapágina de productos. Para equipos que quieren unir rendimiento, SEO, analytics y monetización, usaformación y consultoría Claude Code.

En esta actualización revisé las fuentes oficiales anteriores y rehice los ejemplos con una regla práctica: decidir primero qué imágenes no deben ser lazy. En el flujo de Masa, la combinación estable fue hero eager, capturas inferiores lazy, dimensiones en todas las imágenes,srcset para móvil y un prompt de Claude Code con fallos y tareas de medición desde el inicio.