use-astro-image

Why it matters

The built-in <Image> component automatically optimizes images (WebP/AVIF conversion, responsive srcset, lazy loading, explicit width/height to prevent layout shift). Plain <img> tags with static sources skip all of this. Source-less placeholders populated at runtime are ignored because they cannot be optimized at build time.

See the difference

---
---
<img src="/hero.png" alt="Hero image" />

---
import { Image } from 'astro:assets'
import hero from '../assets/hero.png'
---
<Image src={hero} alt="Hero image" width={800} height={400} />

Configure this check

Override the default severity in your ESLint config:

import astroDoctorPlugin from '@santi020k/eslint-plugin-astro-doctor'

export default [
  astroDoctorPlugin.configs.recommended,
  {
    rules: {
      'astro-doctor/use-astro-image': 'error',
    },
  },
]

Or set the severity for CLI scans in doctor.config.ts:

export default {
  rules: {
    'astro-doctor/use-astro-image': 'error',
  },
}

Use 'error', 'warn', or 'off'. The configuration guide covers presets and per-file overrides.

Keep exploring performance

• no-client-load-overusePrefer client:idle or client:visible over client:load for interactive islands.
• require-image-dimensionsRequire dimensions for public and remote astro:assets images.
• no-blocking-scriptDisallow render-blocking <script src="..."> tags — add defer, async, or type="module".
• no-unprocessed-script-surprisesWarn when script attributes opt out of Astro script processing.

Browse every rule and project audit