cloudflare-next-intl 0.8.57 → 0.8.58

package/README.md

@@ -256,7 +256,7 @@ export default defineConfig({
 ```
 
 ##### What `cloudflareNextIntl()` Does
-1. **Build-Time & Dev Image Optimizer (`imageOptimizer`)**: Automatically scans your image directories (`public/images`, `public/icons`), downscales oversized assets, produces sibling formats (`webp` by default; also supports `avif`, `png`, `jpeg`, `gif`, `tiff`, `heif`, `jp2`, `jxl`), generates 8px `.blur.webp` thumbnails with Next.js-matching SVG Gaussian blur placeholders, and provides transparent `<Image placeholder="blur" />` shimming via virtual modules. When more than one format is generated for an image, the shim renders a `<picture>` with one `<source>` per format — ordered exactly as configured — so the browser picks the best format it supports, with the original untouched file as an `onError` fallback if a generated asset fails to load.
+1. **Build-Time & Dev Image Optimizer (`imageOptimizer`)**: Automatically scans your image directories (`public/images`, `public/icons`), downscales oversized assets, produces sibling formats (`webp` by default; also supports `avif`, `png`, `jpeg`, `gif`, `tiff`, `heif`, `jp2`, `jxl`), generates 8px `.blur.webp` thumbnails with Next.js-matching SVG Gaussian blur placeholders, and provides transparent `<Image placeholder="blur" />` shimming via virtual modules. When more than one format is generated for an image, the shim renders a `<picture>` with one `<source>` per format — ordered exactly as configured — so the browser picks the best format it supports, with the original untouched file as an `onError` fallback if a generated asset fails to load. When the same image is used at different widths across the codebase, each size gets its own generated variant, and each `<Image>` usage automatically resolves to the closest matching size.
 2. **Locale File Bundling & Resolution (`localeFiles`)**: Resolves `@locale-file/*` to your `./messages` directory and transforms dynamic imports into `import.meta.glob('/messages/*.json', { eager: true })` for lightning-fast locale loading on Cloudflare Workers.
 3. **User-Agent Stub (`userAgentStub`)**: Prevents Next.js `user-agent` from importing `node:fs` during workerd runtime execution (which otherwise causes runtime 404 / 500 crashes in Workers proxy/middleware).
 4. **Cloudflare Workers Client Stub (`cfWorkersClientStub`)**: Stubs `cloudflare:workers` in client builds so shared modules can be referenced without client bundling errors.
@@ -310,6 +310,20 @@ import { Image } from "cloudflare-next-intl/image";
 
 Supported props: `formats` (array or `false`), `maxWidth` (number or `false`), `quality` (number), `blur` (`true`, `false`, or `{ size, quality, stdDeviation }`).
 
+##### Multi-Size Variants (Responsive Images)
+
+Every `<Image>` usage's own `width` prop is also scanned. If the same `src` is used at different widths across the codebase — a thumbnail and a hero, say — each distinct width gets its own generated variant instead of the sizes overwriting one another:
+
+```tsx
+// components/Thumbnail.tsx
+<Image src="/images/hero.png" width={200} height={150} alt="thumbnail" />
+
+// components/Hero.tsx
+<Image src="/images/hero.png" width={1200} height={900} alt="hero" />
+```
+
+This produces two sets of generated files (`hero.webp` at the default/full-resolution size and `hero-200w.webp` for the thumbnail), and each `<Image>` call automatically resolves to the closest generated size that is at least as large as its own `width` prop — no manual `srcset` configuration needed. A width larger than any generated variant falls back to the largest one available (never upscales). This is additive to `maxWidth`/`overrides`: an explicit `maxWidth` (via prop or `overrides`) still controls the *default* variant's size, while `width` usages add extra sizes alongside it.
+
 ##### Browser Format Negotiation
 
 When an image's `formats` list has more than one entry, the generated `<source>` tags follow that exact order, so the browser always picks the first format in the list it can decode — no client-side JavaScript is involved:

package/dist/src/image_optimizer/next_image_shim.js

@@ -2,6 +2,23 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import NextImage, { getImageProps as nextGetImageProps } from "next/image";
 import manifest from "virtual:cloudflare-next-intl-images-manifest";
 import { getImageBlurSvg } from "./blur_svg.js";
+/**
+ * When an image was generated at multiple widths (because it's used at
+ * different sizes across the codebase), picks the variant whose width is
+ * closest to what this particular <Image> usage requested — preferring the
+ * smallest variant that is still >= the requested width, to avoid upscaling
+ * visible blur, and falling back to the largest available otherwise.
+ */
+function pickVariant(entry, requestedWidth) {
+    if (!requestedWidth || !entry.variants || entry.variants.length === 0) {
+        return entry;
+    }
+    const atLeast = entry.variants.filter((v) => v.width >= requestedWidth);
+    if (atLeast.length > 0) {
+        return atLeast.reduce((best, v) => (v.width < best.width ? v : best));
+    }
+    return entry.variants.reduce((best, v) => (v.width > best.width ? v : best));
+}
 const manifestData = manifest;
 const images = (manifestData && typeof manifestData === "object" && manifestData.images)
     ? manifestData.images
@@ -51,23 +68,24 @@ function resolveProps(props) {
     let style = props.style;
     const entry = findEntry(src);
     if (entry) {
-        if (entry.src) {
+        const variant = pickVariant(entry, typeof props.width === "number" ? props.width : undefined);
+        if (variant.src) {
             if (typeof src === "string") {
-                src = entry.src;
+                src = variant.src;
             }
             else if (typeof src === "object" && src !== null && "src" in src) {
-                src = { ...src, src: entry.src };
+                src = { ...src, src: variant.src };
             }
             else {
-                src = entry.src;
+                src = variant.src;
             }
         }
-        if (!blurDataURL && props.placeholder === "blur" && entry.blurDataURL) {
-            blurDataURL = getImageBlurSvg(entry.blurDataURL, entry.blurWidth, entry.blurHeight, props.style?.objectFit);
+        if (!blurDataURL && props.placeholder === "blur" && variant.blurDataURL) {
+            blurDataURL = getImageBlurSvg(variant.blurDataURL, variant.blurWidth, variant.blurHeight, props.style?.objectFit);
         }
-        if (!width && !props.fill && entry.width) {
-            width = entry.width;
-            height = entry.height;
+        if (!width && !props.fill && variant.width) {
+            width = variant.width;
+            height = variant.height;
         }
     }
     if (props.placeholder === "blur" && blurDataURL) {
@@ -85,12 +103,15 @@ function resolveProps(props) {
 export default function Image(props) {
     const resolved = resolveProps(props);
     const entry = findEntry(props.src);
-    const alternates = (entry?.sources ?? []).filter((source) => source.src !== entry?.src);
+    const variant = entry
+        ? pickVariant(entry, typeof props.width === "number" ? props.width : undefined)
+        : undefined;
+    const alternates = (variant?.sources ?? []).filter((source) => source.src !== variant?.src);
     if (alternates.length === 0) {
         return _jsx(NextImage, { ...resolved });
     }
     const { props: imgProps } = nextGetImageProps(resolved);
-    const primarySrc = entry?.src ?? String(imgProps.src);
+    const primarySrc = variant?.src ?? String(imgProps.src);
     const originalSrc = entry?.originalSrc;
     const onError = (event) => {
         const img = event.currentTarget;

package/dist/src/image_optimizer/process_image.d.ts

@@ -1,4 +1,5 @@
 import type { ImageFormat, OptimizedImage, OptimizedImageSource, ResolvedBlurOptions, ResolvedOptions } from "./types.js";
+export declare const EXTENSION_BY_FORMAT: Record<ImageFormat, string>;
 export declare function mimeTypeFor(format: ImageFormat | "original", originalSrc: string): string;
 /**
  * <picture> tries <source> tags in document order, so sources must follow the
@@ -10,6 +11,8 @@ export declare function toGeneratedPath(absolutePath: string, publicRoot: string
     targetFile: string;
     targetSrc: string;
 };
+/** Suffixes a generated file/src path with `-{width}w` so multiple widths of the same image don't collide, e.g. hero.webp -> hero-400w.webp. The default (first/primary) width keeps the unsuffixed name for backward compatibility. */
+export declare function withWidthSuffix(pathStr: string, width: number, isDefault: boolean): string;
 export declare function makeBlurDataURL(targetFile: string, sourceWidth: number, sourceHeight: number, blurOptions: ResolvedBlurOptions): Promise<{
     blurDataURL: string;
     blurWidth: number;

package/dist/src/image_optimizer/process_image.js

@@ -27,7 +27,7 @@ const MIME_BY_EXTENSION = {
     ".jp2": "image/jp2",
     ".jxl": "image/jxl",
 };
-const EXTENSION_BY_FORMAT = {
+export const EXTENSION_BY_FORMAT = {
     avif: "avif",
     webp: "webp",
     png: "png",
@@ -64,6 +64,12 @@ export function toGeneratedPath(absolutePath, publicRoot, outDir, root) {
     const targetSrc = `/${path.join(outDirRelativePublic, relative).split(path.sep).join("/")}`;
     return { targetFile, targetSrc };
 }
+/** Suffixes a generated file/src path with `-{width}w` so multiple widths of the same image don't collide, e.g. hero.webp -> hero-400w.webp. The default (first/primary) width keeps the unsuffixed name for backward compatibility. */
+export function withWidthSuffix(pathStr, width, isDefault) {
+    if (isDefault)
+        return pathStr;
+    return pathStr.replace(/(\.[^./]+)$/, `-${width}w$1`);
+}
 export async function makeBlurDataURL(targetFile, sourceWidth, sourceHeight, blurOptions) {
     const blurFile = targetFile.replace(/\.[^.]+$/, ".blur.webp");
     let blurWidth;
@@ -87,10 +93,10 @@ export async function makeBlurDataURL(targetFile, sourceWidth, sourceHeight, blu
         blurHeight,
     };
 }
-async function encodeFormat(targetFile, sourcePath, format, quality, maxWidth, needsResize) {
+async function encodeFormat(targetFile, sourcePath, format, quality, targetWidth) {
     let pipeline = sharp(sourcePath);
-    if (needsResize) {
-        pipeline = pipeline.resize({ width: maxWidth });
+    if (targetWidth !== undefined) {
+        pipeline = pipeline.resize({ width: targetWidth });
     }
     let encoded;
     if (format === "avif") {
@@ -128,40 +134,32 @@ async function encodeFormat(targetFile, sourcePath, format, quality, maxWidth, n
     }
     await encoded.toFile(targetFile);
 }
-export async function processImage(absolutePath, publicRoot, options, root = path.dirname(publicRoot)) {
-    const publicSrc = toPublicSrc(absolutePath, publicRoot);
-    const config = resolveImageConfig(publicSrc, options);
-    const metadata = await sharp(absolutePath).metadata();
-    const sourceWidth = metadata.width;
-    const sourceHeight = metadata.height;
-    const needsResize = typeof config.maxWidth === "number" && sourceWidth > config.maxWidth;
-    const width = needsResize ? config.maxWidth : sourceWidth;
-    const height = needsResize
-        ? Math.round((sourceHeight * config.maxWidth) / sourceWidth)
-        : sourceHeight;
-    const { targetFile, targetSrc } = toGeneratedPath(absolutePath, publicRoot, options.outDir, root);
-    await mkdir(path.dirname(targetFile), { recursive: true });
+/** Resolves one requested width against the source dimensions: `undefined` means "use source size" (no resize), a number is clamped to not exceed the source width (never upscale). */
+function resolveTargetWidth(requestedWidth, sourceWidth) {
+    if (requestedWidth === false)
+        return undefined;
+    return requestedWidth < sourceWidth ? requestedWidth : undefined;
+}
+async function processVariant(absolutePath, publicSrc, targetFile, targetSrc, targetWidth, sourceWidth, sourceHeight, config, isDefault) {
+    const width = targetWidth ?? sourceWidth;
+    const height = targetWidth ? Math.round((sourceHeight * targetWidth) / sourceWidth) : sourceHeight;
     const primaryFormat = config.formats.length > 0
         ? config.formats[0]
         : "original";
-    const primaryFile = primaryFormat === "original"
-        ? targetFile
-        : targetFile.replace(/\.[^.]+$/, `.${EXTENSION_BY_FORMAT[primaryFormat]}`);
-    const primarySrc = primaryFormat === "original"
-        ? targetSrc
-        : targetSrc.replace(/\.[^.]+$/, `.${EXTENSION_BY_FORMAT[primaryFormat]}`);
-    await encodeFormat(primaryFile, absolutePath, primaryFormat, config.quality, config.maxWidth, needsResize);
+    const primaryFile = withWidthSuffix(primaryFormat === "original" ? targetFile : targetFile.replace(/\.[^.]+$/, `.${EXTENSION_BY_FORMAT[primaryFormat]}`), width, isDefault);
+    const primarySrc = withWidthSuffix(primaryFormat === "original" ? targetSrc : targetSrc.replace(/\.[^.]+$/, `.${EXTENSION_BY_FORMAT[primaryFormat]}`), width, isDefault);
+    await encodeFormat(primaryFile, absolutePath, primaryFormat, config.quality, targetWidth);
     const sources = [
         { format: primaryFormat, src: primarySrc, type: mimeTypeFor(primaryFormat, publicSrc) },
     ];
     for (let i = 1; i < config.formats.length; i++) {
         const format = config.formats[i];
         const ext = EXTENSION_BY_FORMAT[format];
-        const siblingFile = targetFile.replace(/\.[^.]+$/, `.${ext}`);
-        await encodeFormat(siblingFile, absolutePath, format, config.quality, config.maxWidth, needsResize);
+        const siblingFile = withWidthSuffix(targetFile.replace(/\.[^.]+$/, `.${ext}`), width, isDefault);
+        await encodeFormat(siblingFile, absolutePath, format, config.quality, targetWidth);
         sources.push({
             format,
-            src: targetSrc.replace(/\.[^.]+$/, `.${ext}`),
+            src: withWidthSuffix(targetSrc.replace(/\.[^.]+$/, `.${ext}`), width, isDefault),
             type: mimeTypeFor(format, publicSrc),
         });
     }
@@ -170,13 +168,36 @@ export async function processImage(absolutePath, publicRoot, options, root = pat
         blurResult = await makeBlurDataURL(primaryFile, width, height, config.blur);
     }
     return {
-        originalSrc: publicSrc,
-        src: primarySrc,
-        sources: sortSources(sources, config.formats),
         width,
         height,
+        src: primarySrc,
+        sources: sortSources(sources, config.formats),
         blurDataURL: blurResult?.blurDataURL,
         blurWidth: blurResult?.blurWidth,
         blurHeight: blurResult?.blurHeight,
     };
 }
+export async function processImage(absolutePath, publicRoot, options, root = path.dirname(publicRoot)) {
+    const publicSrc = toPublicSrc(absolutePath, publicRoot);
+    const config = resolveImageConfig(publicSrc, options);
+    const metadata = await sharp(absolutePath).metadata();
+    const sourceWidth = metadata.width;
+    const sourceHeight = metadata.height;
+    const { targetFile, targetSrc } = toGeneratedPath(absolutePath, publicRoot, options.outDir, root);
+    await mkdir(path.dirname(targetFile), { recursive: true });
+    const defaultTargetWidth = resolveTargetWidth(config.maxWidth, sourceWidth);
+    const requestedWidths = Array.from(new Set(config.extraWidths));
+    const extraTargetWidths = requestedWidths
+        .map((w) => resolveTargetWidth(w, sourceWidth) ?? sourceWidth)
+        .filter((w) => w !== (defaultTargetWidth ?? sourceWidth));
+    const defaultVariant = await processVariant(absolutePath, publicSrc, targetFile, targetSrc, defaultTargetWidth, sourceWidth, sourceHeight, config, true);
+    const variants = [defaultVariant];
+    for (const width of extraTargetWidths) {
+        variants.push(await processVariant(absolutePath, publicSrc, targetFile, targetSrc, width, sourceWidth, sourceHeight, config, false));
+    }
+    return {
+        originalSrc: publicSrc,
+        ...defaultVariant,
+        variants: variants.length > 1 ? variants : undefined,
+    };
+}

package/dist/src/image_optimizer/run.d.ts

@@ -1,6 +1,6 @@
 import type { ImageOverrideOptions, OptimizedImage, ResolvedOptions } from "./types.js";
 export declare function collectImages(dirs: string[], root: string): Promise<string[]>;
-export declare function targetAndSiblingPaths(absolutePath: string, publicRoot: string, options: ResolvedOptions, root: string): string[];
+export declare function targetAndSiblingPaths(absolutePath: string, publicRoot: string, options: ResolvedOptions, root: string): Promise<string[]>;
 /**
  * Merges optimizer overrides scanned from <Image> JSX props with the plugin's
  * centralized `overrides` config, so settings can live at the usage site. An

package/dist/src/image_optimizer/run.js

@@ -1,8 +1,9 @@
 import { readdir, stat } from "node:fs/promises";
 import path from "node:path";
+import sharp from "sharp";
 import { isFresh, loadCache, saveCache } from "./cache.js";
 import { writeManifest } from "./manifest.js";
-import { processImage, toGeneratedPath, toPublicSrc } from "./process_image.js";
+import { EXTENSION_BY_FORMAT, processImage, toGeneratedPath, toPublicSrc, withWidthSuffix } from "./process_image.js";
 import { collectUsedImageOverrides, collectUsedImages } from "./scan_used.js";
 import { resolveImageConfig, SUPPORTED_EXTENSIONS } from "./types.js";
 async function walk(directory, found) {
@@ -31,26 +32,40 @@ export async function collectImages(dirs, root) {
     }
     return found.sort();
 }
-export function targetAndSiblingPaths(absolutePath, publicRoot, options, root) {
-    const publicSrc = toPublicSrc(absolutePath, publicRoot);
-    const config = resolveImageConfig(publicSrc, options);
-    const { targetFile } = toGeneratedPath(absolutePath, publicRoot, options.outDir, root);
+function variantTargetPaths(targetFile, config, width, isDefault) {
     const primaryFormat = config.formats.length > 0
         ? config.formats[0]
         : "original";
-    const primaryFile = primaryFormat === "original"
-        ? targetFile
-        : targetFile.replace(/\.[^.]+$/, `.${primaryFormat}`);
+    const primaryExt = primaryFormat === "original" ? undefined : EXTENSION_BY_FORMAT[primaryFormat];
+    const primaryFile = withWidthSuffix(primaryExt ? targetFile.replace(/\.[^.]+$/, `.${primaryExt}`) : targetFile, width, isDefault);
     const result = [primaryFile];
     for (let i = 1; i < config.formats.length; i++) {
-        const format = config.formats[i];
-        result.push(targetFile.replace(/\.[^.]+$/, `.${format}`));
+        const ext = EXTENSION_BY_FORMAT[config.formats[i]];
+        result.push(withWidthSuffix(targetFile.replace(/\.[^.]+$/, `.${ext}`), width, isDefault));
     }
     if (config.blur.enabled) {
         result.push(primaryFile.replace(/\.[^.]+$/, ".blur.webp"));
     }
     return result;
 }
+export async function targetAndSiblingPaths(absolutePath, publicRoot, options, root) {
+    const publicSrc = toPublicSrc(absolutePath, publicRoot);
+    const config = resolveImageConfig(publicSrc, options);
+    const { targetFile } = toGeneratedPath(absolutePath, publicRoot, options.outDir, root);
+    const metadata = await sharp(absolutePath).metadata();
+    const sourceWidth = metadata.width;
+    const defaultWidth = config.maxWidth !== false && config.maxWidth < sourceWidth
+        ? config.maxWidth
+        : sourceWidth;
+    const result = variantTargetPaths(targetFile, config, defaultWidth, true);
+    const extraWidths = Array.from(new Set(config.extraWidths))
+        .map((w) => (w < sourceWidth ? w : sourceWidth))
+        .filter((w) => w !== defaultWidth);
+    for (const width of extraWidths) {
+        result.push(...variantTargetPaths(targetFile, config, width, false));
+    }
+    return result;
+}
 /**
  * Merges optimizer overrides scanned from <Image> JSX props with the plugin's
  * centralized `overrides` config, so settings can live at the usage site. An
@@ -59,7 +74,14 @@ export function targetAndSiblingPaths(absolutePath, publicRoot, options, root) {
 export function mergeOverrides(scanned, configured) {
     const merged = { ...scanned };
     for (const [src, override] of Object.entries(configured)) {
-        merged[src] = { ...merged[src], ...override };
+        const existing = merged[src];
+        const mergedWidths = existing?.extraWidths || override.extraWidths
+            ? Array.from(new Set([...(existing?.extraWidths ?? []), ...(override.extraWidths ?? [])]))
+            : undefined;
+        merged[src] = { ...existing, ...override };
+        if (mergedWidths) {
+            merged[src].extraWidths = mergedWidths;
+        }
     }
     return merged;
 }
@@ -87,7 +109,7 @@ export async function run(root, options, cacheFile = path.resolve(root, options.
     for (const file of files) {
         const relativeKey = path.relative(root, file);
         const cached = cache[relativeKey];
-        const targets = targetAndSiblingPaths(file, publicRoot, resolvedOptions, root);
+        const targets = await targetAndSiblingPaths(file, publicRoot, resolvedOptions, root);
         const fresh = await isFresh(file, cached, targets);
         if (fresh && cached) {
             entries.push(cached.result);

package/dist/src/image_optimizer/scan_used.d.ts

@@ -7,7 +7,11 @@ export declare function extractImageReferences(code: string): string[];
  * Scans JSX/TSX source for <Image> tags carrying per-image optimizer props
  * (formats / blur / quality / maxWidth) and turns them into override entries
  * keyed by the tag's own src, so settings can live next to usage instead of
- * only in the plugin's centralized `overrides` config.
+ * only in the plugin's centralized `overrides` config. Every tag's own
+ * `width` prop is also collected into `extraWidths`, merged across all usages
+ * of the same src, so the same image used at different sizes (a thumbnail and
+ * a hero, say) gets a separate generated variant for each size instead of one
+ * usage's width silently overwriting another's.
  */
 export declare function extractImageOverrides(code: string): Record<string, ImageOverrideOptions>;
 /**

package/dist/src/image_optimizer/scan_used.js

@@ -57,6 +57,17 @@ export function extractImageReferences(code) {
     }
     return Array.from(refs);
 }
+/** Merges one override into a map by src, unioning `extraWidths` instead of letting the later usage overwrite the earlier one. */
+function mergeOverrideInto(map, src, override) {
+    const existing = map[src];
+    const mergedWidths = existing?.extraWidths || override.extraWidths
+        ? Array.from(new Set([...(existing?.extraWidths ?? []), ...(override.extraWidths ?? [])]))
+        : undefined;
+    map[src] = { ...existing, ...override };
+    if (mergedWidths) {
+        map[src].extraWidths = mergedWidths;
+    }
+}
 const IMAGE_FORMATS = [
     "avif", "webp", "png", "jpeg", "gif", "tiff", "heif", "jp2", "jxl",
 ];
@@ -96,7 +107,11 @@ function parseBlurAttr(raw) {
  * Scans JSX/TSX source for <Image> tags carrying per-image optimizer props
  * (formats / blur / quality / maxWidth) and turns them into override entries
  * keyed by the tag's own src, so settings can live next to usage instead of
- * only in the plugin's centralized `overrides` config.
+ * only in the plugin's centralized `overrides` config. Every tag's own
+ * `width` prop is also collected into `extraWidths`, merged across all usages
+ * of the same src, so the same image used at different sizes (a thumbnail and
+ * a hero, say) gets a separate generated variant for each size instead of one
+ * usage's width silently overwriting another's.
  */
 export function extractImageOverrides(code) {
     const overrides = {};
@@ -122,6 +137,10 @@ export function extractImageOverrides(code) {
             if (parsed !== undefined)
                 override.maxWidth = parsed;
         }
+        const widthMatch = attrs.match(/\bwidth\s*=\s*\{?(\d+)\}?/);
+        if (widthMatch) {
+            override.extraWidths = [Number(widthMatch[1])];
+        }
         const qualityMatch = attrs.match(/\bquality\s*=\s*\{?(\d+)\}?/);
         if (qualityMatch) {
             override.quality = Number(qualityMatch[1]);
@@ -133,7 +152,7 @@ export function extractImageOverrides(code) {
                 override.blur = parsed;
         }
         if (Object.keys(override).length > 0) {
-            overrides[src] = { ...overrides[src], ...override };
+            mergeOverrideInto(overrides, src, override);
         }
     }
     return overrides;
@@ -184,7 +203,7 @@ export async function collectUsedImageOverrides(root, publicDir = "public") {
         const fileOverrides = extractImageOverrides(content);
         for (const [src, override] of Object.entries(fileOverrides)) {
             const publicSrc = resolvePublicSrc(src);
-            overrides[publicSrc] = { ...overrides[publicSrc], ...override };
+            mergeOverrideInto(overrides, publicSrc, override);
         }
     }
     return overrides;

package/dist/src/image_optimizer/types.d.ts

@@ -14,6 +14,13 @@ export interface ImageOverrideOptions {
     formats?: ImageFormat[] | false;
     /** Max width to downscale, or `false` to preserve original dimensions. Default: inherits global */
     maxWidth?: number | false;
+    /**
+     * Additional widths to also generate as separate variants, e.g. when the
+     * same src is used at different sizes across the codebase (a thumbnail and
+     * a hero). Populated automatically by scanning <Image width=...> usages;
+     * merges (never overwrites) across multiple usages of the same src.
+     */
+    extraWidths?: number[];
     /** Compression quality (1-100). Default: inherits global */
     quality?: number;
     /** Blur placeholder settings for this image, or `false` to disable. Default: inherits global */
@@ -67,6 +74,7 @@ export interface ResolvedOptions {
 }
 export interface ResolvedImageConfig {
     maxWidth: number | false;
+    extraWidths: number[];
     quality: number;
     formats: ImageFormat[];
     blur: ResolvedBlurOptions;
@@ -76,16 +84,25 @@ export interface OptimizedImageSource {
     src: string;
     type: string;
 }
-export interface OptimizedImage {
-    originalSrc: string;
-    src: string;
-    sources?: OptimizedImageSource[];
+export interface OptimizedImageVariant {
     width: number;
     height: number;
+    src: string;
+    sources?: OptimizedImageSource[];
     blurDataURL?: string;
     blurWidth?: number;
     blurHeight?: number;
 }
+/**
+ * `src`/`width`/`height`/`sources`/`blur*` mirror the default variant (the
+ * first one generated) so existing single-size lookups keep working; `variants`
+ * carries every width actually requested via <Image width=...> across the
+ * codebase, so the component can pick the closest match to what's rendered.
+ */
+export interface OptimizedImage extends OptimizedImageVariant {
+    originalSrc: string;
+    variants?: OptimizedImageVariant[];
+}
 export interface ManifestData {
     images: Record<string, OptimizedImage>;
 }

package/dist/src/image_optimizer/types.js

@@ -61,6 +61,7 @@ export function resolveImageConfig(publicSrc, options) {
     if (!override) {
         return {
             maxWidth: options.maxWidth,
+            extraWidths: [],
             quality: options.quality,
             formats: options.formats,
             blur: options.blur,
@@ -80,5 +81,6 @@ export function resolveImageConfig(publicSrc, options) {
     const blur = override.blur !== undefined
         ? resolveBlurOptions(override.blur, options.blur)
         : options.blur;
-    return { maxWidth, quality, formats, blur };
+    const extraWidths = override.extraWidths ? [...override.extraWidths] : [];
+    return { maxWidth, extraWidths, quality, formats, blur };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.8.57",
+  "version": "0.8.58",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",