@power-seo/images

Alt text auditing, CWV-aware lazy loading checks, WebP/AVIF format recommendations, and image sitemap XML generation with the <image:image> extension.

@power-seo/images is a focused toolkit for every image-related SEO concern. Images are consistently among the top contributors to poor Core Web Vitals scores and lost organic visibility — yet they are also the easiest wins once you have the right analysis in place. This package gives you precise, programmatic insight into your image SEO health.

The alt text auditor catches not just empty alt attributes but the subtler issues: filenames used as alt text, alt text that is too short to be meaningful, duplicate alt text across multiple images, and whether your focus keyphrase appears in at least one image's alt text. The lazy loading auditor is CWV-aware — it will flag above-the-fold images that have loading="lazy" applied (which delays LCP) and below-the-fold images that are missing it (which wastes bandwidth). The format analyzer detects each image's current format by URL extension and recommends modern alternatives (WebP, AVIF) for formats that lack compression efficiency. Finally, generateImageSitemap produces standards-compliant XML using Google's image: namespace extension so your images appear in image search results.

Zero dependencies — pure TypeScript; no external runtime libraries required.

Why @power-seo/images?

| | Without | With | | ------------------ | --------------------- | -------------------------------------------------------- | | Alt text quality | ❌ Spot-check | ✅ 6 issue types: missing, short, filename, duplicate... | | CWV-aware loading | ❌ Generic advice | ✅ Above/below-fold-aware lazy loading audit | | Format detection | ❌ Manual | ✅ JPEG/PNG/GIF → WebP/AVIF recommendations | | Image sitemap | ❌ Write XML manually | ✅ Standards-compliant image: namespace XML | | Scoring | ❌ None | ✅ Per-analyzer 0–100 scores | | LCP protection | ❌ Unknown | ✅ Flags hero images incorrectly marked lazy | | TypeScript support | ❌ Untyped | ✅ Full type coverage for all inputs and results |

Features

• Alt text audit — detects missing alt attributes, empty alt text on non-decorative images, alt text that is too short (under 5 characters), filename patterns used as alt text (e.g., IMG_1234), duplicate alt text across multiple images, and keyphrase presence in at least one image's alt text
• CWV-aware lazy loading audit — flags above-the-fold images with loading="lazy" (LCP regression risk), missing loading="lazy" on below-the-fold images (unnecessary bandwidth), and images without explicit width/height dimensions (layout shift / CLS regression)
• Format detection — detectFormat(src) identifies JPEG, PNG, WebP, AVIF, GIF, and SVG from URL path or filename extension
• Format recommendation engine — getFormatRecommendation(format) returns specific upgrade recommendations: JPEG/PNG → WebP or AVIF, GIF → WebP animated or video, with rationale for each
• Batch format analysis — analyzeImageFormats(input) audits all images on a page and returns a FormatAuditResult with per-image recommendations and an overall optimization score
• HTML image extraction — extractImageEntries(html, baseUrl) parses an HTML string and extracts all <img> elements with their src, alt, and dimension attributes, resolving relative URLs against the provided base
• Image sitemap generation — generateImageSitemap(pages) produces valid XML conforming to Google's image sitemap specification with <image:loc>, <image:title>, and <image:caption> elements
• Severity-leveled issues — every image issue carries a severity of error, warning, or info so you can triage and filter
• Type-safe throughout — complete TypeScript types covering all inputs, outputs, formats, and issue structures
• Zero dependencies — pure TypeScript, no external runtime libraries

Comparison

| Feature | @power-seo/images | sharp | Lighthouse | next/image | imagemin | | ---------------------------- | :---------------: | :-----: | :--------: | :--------: | :------: | | Alt text quality audit | ✅ | ❌ | Partial | ❌ | ❌ | | CWV-aware lazy loading audit | ✅ | ❌ | Partial | ❌ | ❌ | | Format recommendations | ✅ | ❌ | Partial | ✅ | Partial | | Image sitemap generation | ✅ | ❌ | ❌ | ❌ | ❌ | | Severity-leveled issues | ✅ | ❌ | ✅ | ❌ | ❌ | | Programmatic API | ✅ | ✅ | Partial | ✅ | ✅ | | Zero dependencies | ✅ | ❌ | ❌ | ❌ | ❌ | | TypeScript-first | ✅ | Partial | ❌ | ✅ | ❌ |

Installation

npm install @power-seo/images

yarn add @power-seo/images

pnpm add @power-seo/images

Quick Start

import { analyzeAltText, auditLazyLoading, analyzeImageFormats } from '@power-seo/images';

const images = [
  { src: '/hero.jpg', alt: '', loading: 'lazy', isAboveFold: true, width: 1200, height: 630 },
  {
    src: '/IMG_1234.png',
    alt: 'IMG_1234',
    loading: undefined,
    isAboveFold: false,
    width: 800,
    height: 600,
  },
  {
    src: '/product.webp',
    alt: 'Blue widget',
    loading: 'lazy',
    isAboveFold: false,
    width: 400,
    height: 400,
  },
];

// Alt text issues
const altResult = analyzeAltText(images, 'blue widget');
console.log(altResult.issues);
// [{ id: 'alt-missing', title: 'Missing alt attribute', description: '...', severity: 'error', image: {...} },
//  { id: 'filename-as-alt', title: 'Filename used as alt', description: '...', severity: 'warning', image: {...} }]

// Lazy loading issues
const lazyResult = auditLazyLoading(images);
console.log(lazyResult.issues);
// [{ src: '/hero.jpg', type: 'lazy-above-fold', severity: 'error', message: '...' },
//  { src: '/IMG_1234.png', type: 'missing-lazy', severity: 'warning', message: '...' }]

// Format recommendations
const formatResult = analyzeImageFormats(images);
console.log(formatResult.recommendations);
// [{ src: '/hero.jpg', currentFormat: 'jpeg', isModern: false, recommendation: '...' }, ...]

Usage

Alt Text Analysis

analyzeAltText performs a comprehensive quality check on every image's alt attribute.

import { analyzeAltText } from '@power-seo/images';
import type { ImageAnalysisResult, ImageIssue } from '@power-seo/images';

const result: ImageAnalysisResult = analyzeAltText(
  [
    { src: '/hero.jpg', alt: '' }, // missing alt
    { src: '/icon.png', alt: 'i' }, // too short
    { src: '/IMG_9821.jpg', alt: 'IMG_9821' }, // filename as alt
    { src: '/team-photo.jpg', alt: 'Team photo' }, // ok
    { src: '/product.webp', alt: 'Blue widget on white background' }, // good, has keyphrase
    { src: '/bg.jpg', alt: '' }, // decorative — ok if marked
  ],
  'blue widget',
);

result.issues.forEach((issue: ImageIssue) => {
  console.log(`[${issue.severity}] ${issue.src}: ${issue.message}`);
});

console.log(`Keyphrase found in alt text: ${result.keyphraseInAlt}`);
console.log(`Images with issues: ${result.issueCount}/${result.totalImages}`);

The following issue types are detected:

| Type | Severity | Description | | ------------------- | --------- | ------------------------------------------------------------------------------------------ | | missing-alt | error | The alt attribute is absent entirely | | empty-alt | warning | The alt attribute exists but is an empty string (appropriate only for decorative images) | | alt-too-short | warning | The alt text is present but fewer than 5 characters | | filename-as-alt | warning | The alt text appears to be a filename (e.g., IMG_1234, photo.jpg) | | duplicate-alt | info | The same alt text is used on multiple images | | keyphrase-missing | info | No image on the page has the focus keyphrase in its alt text |

Lazy Loading Audit

auditLazyLoading evaluates loading attributes with Core Web Vitals awareness.

import { auditLazyLoading } from '@power-seo/images';
import type { LazyLoadingAuditResult } from '@power-seo/images';

const result: LazyLoadingAuditResult = auditLazyLoading([
  // Above fold — should NOT be lazy-loaded (LCP risk)
  { src: '/hero.jpg', loading: 'lazy', isAboveFold: true, width: 1200, height: 630 },
  // Below fold — SHOULD be lazy-loaded (bandwidth saving)
  { src: '/section2.jpg', loading: undefined, isAboveFold: false, width: 800, height: 500 },
  // Good: above fold, eagerly loaded
  { src: '/logo.png', loading: 'eager', isAboveFold: true, width: 200, height: 60 },
  // Good: below fold, lazy-loaded
  { src: '/footer.jpg', loading: 'lazy', isAboveFold: false, width: 600, height: 400 },
  // Missing dimensions — causes CLS
  { src: '/promo.jpg', loading: 'lazy', isAboveFold: false },
]);

result.issues.forEach((issue) => {
  console.log(`[${issue.severity}] ${issue.title}: ${issue.description}`);
});

| Issue type | Severity | Description | | -------------------- | --------- | ----------------------------------------------------------------------- | | lazy-above-fold | error | Above-fold image with loading="lazy" — delays LCP | | missing-lazy | warning | Below-fold image without loading="lazy" — wastes bandwidth | | missing-dimensions | warning | Image without explicit width and height — causes layout shift (CLS) |

Format Detection and Recommendations

import { detectFormat, getFormatRecommendation } from '@power-seo/images';
import type { ImageFormat } from '@power-seo/images';

// Detect format from a URL or filename
const format: ImageFormat = detectFormat('/images/hero.jpg');
// 'jpeg'

detectFormat('https://example.com/icon.png'); // 'png'
detectFormat('/animation.gif'); // 'gif'
detectFormat('/photo.webp'); // 'webp'
detectFormat('/image.avif'); // 'avif'
detectFormat('/logo.svg'); // 'svg'

// Get a recommendation for the detected format
const recommendation = getFormatRecommendation('jpeg');
// 'Convert to WebP or AVIF for 25-50% smaller file sizes with equivalent quality.'

const gifRec = getFormatRecommendation('gif');
// 'Convert animated GIFs to WebP or MP4 video for dramatically smaller file sizes.'

Batch Format Analysis

analyzeImageFormats evaluates all images on a page and produces a structured audit result.

import { analyzeImageFormats } from '@power-seo/images';
import type { FormatAuditResult } from '@power-seo/images';

const result: FormatAuditResult = analyzeImageFormats([
  { src: '/hero.jpg' },
  { src: '/thumbnail.png' },
  { src: '/animation.gif' },
  { src: '/logo.svg' },
  { src: '/banner.webp' },
]);

console.log(`Total images: ${result.totalImages}`);
console.log(`Modern formats: ${result.modernFormatCount}`);
console.log(`Legacy formats: ${result.legacyFormatCount}`);

result.results.forEach((item) => {
  if (!item.isModern && item.recommendation) {
    console.log(`${item.src}: ${item.recommendation}`);
  }
});

Image Sitemap Generation

Generate a Google-compliant image sitemap with the image: XML namespace extension.

import { generateImageSitemap } from '@power-seo/images';
import type { ImageSitemapPage } from '@power-seo/images';

const pages: ImageSitemapPage[] = [
  {
    pageUrl: 'https://example.com/products/widget',
    images: [
      { src: '/products/widget.jpg', alt: 'Blue widget' },
      { src: '/products/widget-detail.webp', alt: 'Widget detail view' },
    ],
  },
  {
    pageUrl: 'https://example.com/products/gadget',
    images: [{ src: '/products/gadget.jpg', alt: 'Premium gadget' }],
  },
];

// Generate image sitemap XML
const sitemapXml = generateImageSitemap(pages);

// Save to public/image-sitemap.xml
console.log(sitemapXml);

Full Page Image Audit

Combine all analyzers for a complete image health report on a single page.

import { analyzeAltText, auditLazyLoading, analyzeImageFormats } from '@power-seo/images';

const images: ImageInfo[] = [
  {
    src: '/blog/hero.jpg',
    alt: 'Article hero image',
    loading: 'eager',
    isAboveFold: true,
    width: 1200,
    height: 630,
  },
  {
    src: '/blog/section1.webp',
    alt: '',
    loading: undefined,
    isAboveFold: false,
    width: 800,
    height: 400,
  },
  {
    src: '/blog/my-post-topic.jpg',
    alt: 'My post topic illustration',
    loading: 'lazy',
    isAboveFold: false,
    width: 600,
    height: 400,
  },
];

const altResult = analyzeAltText(images, 'my post topic');
const lazyResult = auditLazyLoading(images);
const formatResult = analyzeImageFormats(images);

console.log(`Alt text issues: ${altResult.issueCount}/${altResult.totalImages}`);
console.log(`Lazy loading issues: ${lazyResult.issues.length}`);
console.log(`Legacy formats: ${formatResult.legacyFormatCount}/${formatResult.totalImages}`);

API Reference

analyzeAltText(images, focusKeyphrase?)

function analyzeAltText(images: ImageInfo[], focusKeyphrase?: string): ImageAuditResult;

| Parameter | Type | Default | Description | | ---------------- | ------------- | -------- | ----------------------------------------------------------------- | | images | ImageInfo[] | required | Array of image objects with src, alt, and optional properties | | focusKeyphrase | string | — | Optional focus keyword to check for presence in alt text |

Returns ImageAuditResult:

• totalImages: number — Total images analyzed
• score: number — Overall alt text quality score (0–100)
• maxScore: number — Maximum possible score
• issues: ImageIssue[] — Array of detected issues
• perImage: ImageAnalysisResult[] — Per-image analysis results
• recommendations: string[] — Actionable improvement recommendations | input.keyphrase | string | '' | Focus keyphrase to check for in alt text | | input.minAltLength | number | 5 | Minimum character length for meaningful alt text |

Returns ImageAuditResult:

| Property | Type | Description | | ----------------- | ----------------------- | ----------------------------------------------- | | totalImages | number | Total number of images analyzed | | score | number | Alt text quality score 0–100 | | maxScore | number | Maximum possible score (for reference) | | issues | ImageIssue[] | Array of detected alt text issues | | perImage | ImageAnalysisResult[] | Per-image analysis results | | recommendations | string[] | Human-readable alt text improvement suggestions |

auditLazyLoading(input)

| Parameter | Type | Default | Description | | -------------- | ------------- | -------- | ------------------------------------------------------------------------------ | | input.images | ImageInfo[] | required | Array of image objects with src, loading, isAboveFold, width, height |

Returns LazyLoadingAuditResult:

| Property | Type | Description | | ----------------- | -------------- | -------------------------------------------- | | totalImages | number | Total number of images analyzed | | issues | ImageIssue[] | Array of detected lazy loading issues | | recommendations | string[] | Human-readable lazy loading improvement tips |

detectFormat(src)

| Parameter | Type | Default | Description | | --------- | -------- | -------- | -------------------------- | | src | string | required | Image URL or filename path |

Returns ImageFormat ('jpeg' | 'png' | 'webp' | 'avif' | 'gif' | 'svg' | 'bmp' | 'ico' | 'tiff' | 'unknown').

getFormatRecommendation(format)

| Parameter | Type | Default | Description | | --------- | ------------- | -------- | ------------------------------- | | format | ImageFormat | required | The current format of the image |

Returns string | undefined — a human-readable recommendation for upgrading the image format, or undefined if no recommendation is available.

analyzeImageFormats(input)

| Parameter | Type | Default | Description | | -------------- | ------------- | -------- | ------------------------------------------------ | | input.images | ImageInfo[] | required | Array of images with at minimum a src property |

Returns FormatAuditResult:

| Property | Type | Description | | ------------------- | ------------------------ | ---------------------------------------------------------- | | totalImages | number | Total number of images analyzed | | modernFormatCount | number | Number of images using modern formats (webp, avif) | | legacyFormatCount | number | Number of images using legacy formats (jpeg, png, etc) | | results | FormatAnalysisResult[] | Per-image analysis with current format and recommendations | | recommendations | string[] | Human-readable format upgrade suggestions |

extractImageEntries(html, baseUrl)

| Parameter | Type | Default | Description | | --------- | -------- | -------- | ------------------------------------------- | | html | string | required | HTML string to parse for <img> elements | | baseUrl | string | required | Base URL for resolving relative src paths |

Returns SitemapImage[].

generateImageSitemap(pages)

| Parameter | Type | Default | Description | | --------- | -------------------- | -------- | -------------------------------------------------------------- | | pages | ImageSitemapPage[] | required | Array of { pageUrl: string; images: SitemapImage[] } objects |

Returns string — well-formed XML image sitemap with Google's image: namespace.

Types

import type {
  ImageFormat, // 'jpeg' | 'png' | 'webp' | 'avif' | 'gif' | 'svg' | 'unknown'
  ImageInfo, // { src, alt?, loading?, isAboveFold?, width?, height? }
  ImageIssueSeverity, // 'error' | 'warning' | 'info' | 'pass'
  ImageIssue, // { id, title, description, severity, image? }
  ImageAnalysisResult, // { src, issues, score, maxScore }
  ImageAuditResult, // Combined result from multiple analyzers
  ImageSitemapPage, // { pageUrl: string; images: SitemapImage[] }
  FormatAnalysisResult, // { src, currentFormat, isModern, recommendation? }
  FormatAuditResult, // { totalImages, modernFormatCount, legacyFormatCount, results, recommendations }
  LazyLoadingAuditResult, // { totalImages, issues, recommendations }
  SitemapImage, // { loc, title?, caption? }
} from '@power-seo/images';

Use Cases

• E-commerce platforms — audit product image alt text and format optimization at scale before publishing
• CMS integrations — validate image SEO health before content goes live; surface issues to authors
• Performance optimization pipelines — run format recommendations as a CI step before deployment
• Image sitemap automation — generate and update Google image sitemaps on every content change
• CWV optimization — identify LCP-damaging lazy-loaded hero images automatically across all pages

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Zero dependencies — no external runtime libraries required
• Framework-agnostic — works in Next.js, Remix, Vite, Node.js, Edge
• SSR compatible — no browser-specific APIs; safe for server-side use
• Edge runtime safe — no Node.js-specific APIs; runs in Cloudflare Workers, Vercel Edge, Deno
• Tree-shakeable — "sideEffects": false with named exports per analyzer function
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage

Supply Chain Security

• No install scripts (postinstall, preinstall)
• No runtime network access
• No eval or dynamic code execution
• CI-signed builds — all releases published via verified github.com/CyberCraftBD/power-seo workflow
• Safe for SSR, Edge, and server environments

The @power-seo Ecosystem

All 17 packages are independently installable — use only what you need.

| Package | Install | Description | | ------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------- | | @power-seo/core | npm i @power-seo/core | Framework-agnostic utilities, types, validators, and constants | | @power-seo/react | npm i @power-seo/react | React SEO components — meta, Open Graph, Twitter Card, breadcrumbs | | @power-seo/meta | npm i @power-seo/meta | SSR meta helpers for Next.js App Router, Remix v2, and generic SSR | | @power-seo/schema | npm i @power-seo/schema | Type-safe JSON-LD structured data — 23 builders + 22 React components | | @power-seo/content-analysis | npm i @power-seo/content-analysis | Yoast-style SEO content scoring engine with React components | | @power-seo/readability | npm i @power-seo/readability | Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI | | @power-seo/preview | npm i @power-seo/preview | SERP, Open Graph, and Twitter/X Card preview generators | | @power-seo/sitemap | npm i @power-seo/sitemap | XML sitemap generation, streaming, index splitting, and validation | | @power-seo/redirects | npm i @power-seo/redirects | Redirect engine with Next.js, Remix, and Express adapters | | @power-seo/links | npm i @power-seo/links | Link graph analysis — orphan detection, suggestions, equity scoring | | @power-seo/audit | npm i @power-seo/audit | Full SEO audit engine — meta, content, structure, performance rules | | @power-seo/images | npm i @power-seo/images | Image SEO — alt text, lazy loading, format analysis, image sitemaps | | @power-seo/ai | npm i @power-seo/ai | LLM-agnostic AI prompt templates and parsers for SEO tasks | | @power-seo/analytics | npm i @power-seo/analytics | Merge GSC + audit data, trend analysis, ranking insights, dashboard | | @power-seo/search-console | npm i @power-seo/search-console | Google Search Console API — OAuth2, service account, URL inspection | | @power-seo/integrations | npm i @power-seo/integrations | Semrush and Ahrefs API clients with rate limiting and pagination | | @power-seo/tracking | npm i @power-seo/tracking | GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management |

About CyberCraft Bangladesh

CyberCraft Bangladesh is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.

© 2026 CyberCraft Bangladesh · Released under the MIT License