cloudflare-next-intl 0.8.56 → 0.8.57

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 modern `.avif` and `.webp` formats, generates 8px `.blur.webp` thumbnails with Next.js-matching SVG Gaussian blur placeholders, and provides transparent `<Image placeholder="blur" />` shimming via virtual modules.
+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.
 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.
@@ -274,10 +274,11 @@ export default defineConfig({
         cloudflareNextIntl({
             imageOptimizer: {                     // Image optimizer configuration (or `false` to disable)
                 maxWidth: 1920,                   // Downscale max width limit (default: 1920, or `false`)
-                formats: ["avif", "webp"],        // Target sibling formats (default: ["avif", "webp"], or `false`)
+                formats: ["avif", "webp"],        // Target sibling formats, in browser-preference order (default: ["webp"], or `false`).
+                                                   // Also supports: "png", "jpeg", "gif", "tiff", "heif", "jp2", "jxl"
                 quality: 80,                      // Compression quality (default: 80)
                 blur: { quality: 70, stdDeviation: 20 }, // Next.js blur placeholder options (or `false`)
-                overrides: {                      // Per-image overrides keyed by public src path
+                overrides: {                      // Per-image overrides keyed by public src path (wins over scanned <Image> props)
                     "/images/hero.png": { maxWidth: false, formats: ["webp"], blur: { quality: 80 } },
                     "/images/logo.png": { formats: false, blur: false },
                 },
@@ -296,6 +297,39 @@ export default defineConfig({
 Individual standalone plugins are also exported if you only need a specific feature:
 `imageOptimizerPlugin` (or `imageOptimizer`), `buildIdAsset`, `localeFilePlugin`, `userAgentStubPlugin`, `cfWorkersClientStubPlugin`.
 
+##### Per-Image Optimizer Settings
+
+Instead of (or in addition to) the centralized `overrides` config, settings can be set directly as props on individual `<Image>` usages. The build scans your JSX for these props and applies them per image — a matching `overrides` entry for the same `src` still wins if both are set:
+
+```tsx
+import { Image } from "cloudflare-next-intl/image";
+
+<Image src="/images/hero.png" formats={["avif", "webp"]} quality={95} blur={{ size: 16, quality: 90 }} />
+<Image src="/images/icon.svg" formats={false} blur={false} maxWidth={false} />
+```
+
+Supported props: `formats` (array or `false`), `maxWidth` (number or `false`), `quality` (number), `blur` (`true`, `false`, or `{ size, quality, stdDeviation }`).
+
+##### 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:
+
+```tsx
+<Image src="/images/hero.png" formats={["avif", "webp"]} />
+```
+
+renders as:
+
+```html
+<picture>
+  <source type="image/avif" srcset="/generated/images/hero.avif" />
+  <source type="image/webp" srcset="/generated/images/hero.webp" />
+  <img src="/generated/images/hero.avif" ... />
+</picture>
+```
+
+If the primary generated asset fails to load at runtime (e.g. a missing/corrupted build output), the `<img>` falls back to the original, unprocessed source file automatically via `onError`.
+
 ```tsx
 // Client Components ("use client")
 import { useLocale } from "cloudflare-next-intl/use";

package/bin/image_optimizer.mjs

@@ -4,9 +4,16 @@ import { run } from "../dist/src/image_optimizer/run.js";
 import { resolveOptions } from "../dist/src/image_optimizer/types.js";
 
 const root = process.cwd();
-const options = resolveOptions();
+const args = process.argv.slice(2);
+const onlyUsed = !args.includes("--all");
+const options = resolveOptions({ onlyUsed });
 const cacheFile = path.resolve(root, options.cacheDir, "manifest.json");
 
-console.log("[cfni-image-optimizer] scanning images in", options.dirs.join(", "));
+if (onlyUsed) {
+    console.log("[cfni-image-optimizer] scanning code for used <Image> references...");
+} else {
+    console.log("[cfni-image-optimizer] scanning all images in", options.dirs.join(", "));
+}
+
 const entries = await run(root, options, cacheFile);
 console.log(`[cfni-image-optimizer] processed ${entries.length} images into ${options.outDir}`);

package/dist/src/image.d.ts

@@ -0,0 +1 @@
+export { default, default as Image, getImageProps, getImageBlurSvg, type ManifestEntry, } from "./image_optimizer/next_image_shim.js";

package/dist/src/image.js

@@ -0,0 +1 @@
+export { default, default as Image, getImageProps, getImageBlurSvg, } from "./image_optimizer/next_image_shim.js";

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

@@ -4,5 +4,6 @@ export { processImage, makeBlurDataURL, toGeneratedPath, toPublicSrc, } from "./
 export { renderManifest, writeManifest, } from "./manifest.js";
 export { isFresh, loadCache, saveCache, type CacheEntry, type CacheData, } from "./cache.js";
 export { collectImages, run, } from "./run.js";
+export { collectUsedImages, findCodeFiles, extractImageReferences, CODE_EXTENSIONS, IGNORED_DIRS, } from "./scan_used.js";
 export { getImageBlurSvg, } from "./blur_svg.js";
 export { type ManifestEntry, } from "./next_image_shim.js";

package/dist/src/image_optimizer/index.js

@@ -4,4 +4,5 @@ export { processImage, makeBlurDataURL, toGeneratedPath, toPublicSrc, } from "./
 export { renderManifest, writeManifest, } from "./manifest.js";
 export { isFresh, loadCache, saveCache, } from "./cache.js";
 export { collectImages, run, } from "./run.js";
+export { collectUsedImages, findCodeFiles, extractImageReferences, CODE_EXTENSIONS, IGNORED_DIRS, } from "./scan_used.js";
 export { getImageBlurSvg, } from "./blur_svg.js";

package/dist/src/image_optimizer/next_image_shim.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+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";
@@ -33,6 +33,16 @@ function findEntry(srcVal) {
     }
     return undefined;
 }
+/** Swap the format extension of every URL in a generated srcset. */
+function retargetSrcSet(srcSet, fromSrc, toSrc) {
+    if (!srcSet)
+        return srcSet;
+    const fromEncoded = encodeURIComponent(fromSrc);
+    const toEncoded = encodeURIComponent(toSrc);
+    return srcSet
+        .split(fromEncoded).join(toEncoded)
+        .split(fromSrc).join(toSrc);
+}
 function resolveProps(props) {
     let src = props.src;
     let blurDataURL = props.blurDataURL;
@@ -74,7 +84,24 @@ function resolveProps(props) {
 }
 export default function Image(props) {
     const resolved = resolveProps(props);
-    return _jsx(NextImage, { ...resolved });
+    const entry = findEntry(props.src);
+    const alternates = (entry?.sources ?? []).filter((source) => source.src !== entry?.src);
+    if (alternates.length === 0) {
+        return _jsx(NextImage, { ...resolved });
+    }
+    const { props: imgProps } = nextGetImageProps(resolved);
+    const primarySrc = entry?.src ?? String(imgProps.src);
+    const originalSrc = entry?.originalSrc;
+    const onError = (event) => {
+        const img = event.currentTarget;
+        if (originalSrc && img.src !== originalSrc && !img.src.endsWith(originalSrc)) {
+            img.srcset = "";
+            img.src = originalSrc;
+        }
+    };
+    return (_jsxs("picture", { children: [alternates.map((source) => (_jsx("source", { type: source.type, sizes: imgProps.sizes, srcSet: imgProps.srcSet
+                    ? retargetSrcSet(imgProps.srcSet, primarySrc, source.src)
+                    : source.src }, source.src))), _jsx("img", { ...imgProps, onError: onError })] }));
 }
 export function getImageProps(props) {
     const resolved = resolveProps(props);

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

@@ -0,0 +1 @@
+export {};

package/dist/src/image_optimizer/process_image.bench.js

@@ -0,0 +1,68 @@
+import { bench, describe } from "vitest";
+import sharp from "sharp";
+import { makeTempDir, writeFixtureJpg, writeFixturePng } from "../test_utils/image_optimizer_test_helpers.js";
+import { processImage } from "./process_image.js";
+import { resolveOptions } from "./types.js";
+const root = await makeTempDir();
+const smallPng = await writeFixturePng(root, "small.png", 200, 150);
+const largePng = await writeFixturePng(root, "large.png", 2400, 1600);
+const photoJpg = await writeFixtureJpg(root, "photo.jpg", 1600, 1200);
+const largeBuffer = await sharp(largePng).toBuffer();
+const photoBuffer = await sharp(photoJpg).toBuffer();
+describe("avif encode: effort trade-off", () => {
+    bench("effort 0 (fastest, default quality)", async () => {
+        await sharp(photoBuffer).avif({ quality: 80, effort: 0 }).toBuffer();
+    });
+    bench("effort 4 (sharp default)", async () => {
+        await sharp(photoBuffer).avif({ quality: 80 }).toBuffer();
+    });
+    bench("effort 9 (max compression, slowest)", async () => {
+        await sharp(photoBuffer).avif({ quality: 80, effort: 9 }).toBuffer();
+    });
+});
+describe("webp encode: effort trade-off", () => {
+    bench("effort 0 (fastest)", async () => {
+        await sharp(photoBuffer).webp({ quality: 80, effort: 0 }).toBuffer();
+    });
+    bench("effort 4 (sharp default)", async () => {
+        await sharp(photoBuffer).webp({ quality: 80 }).toBuffer();
+    });
+    bench("effort 6 (max compression, slowest)", async () => {
+        await sharp(photoBuffer).webp({ quality: 80, effort: 6 }).toBuffer();
+    });
+});
+describe("resize kernel trade-off (downscale 2400x1600 -> 800)", () => {
+    bench("kernel: nearest (fastest, lowest quality)", async () => {
+        await sharp(largeBuffer).resize({ width: 800, kernel: "nearest" }).webp({ quality: 80 }).toBuffer();
+    });
+    bench("kernel: lanczos3 (sharp default)", async () => {
+        await sharp(largeBuffer).resize({ width: 800 }).webp({ quality: 80 }).toBuffer();
+    });
+    bench("kernel: mitchell (mid-quality)", async () => {
+        await sharp(largeBuffer).resize({ width: 800, kernel: "mitchell" }).webp({ quality: 80 }).toBuffer();
+    });
+});
+describe("mozjpeg vs baseline jpeg encode", () => {
+    bench("baseline jpeg", async () => {
+        await sharp(photoBuffer).jpeg({ quality: 80 }).toBuffer();
+    });
+    bench("mozjpeg (current production setting)", async () => {
+        await sharp(photoBuffer).jpeg({ quality: 80, mozjpeg: true }).toBuffer();
+    });
+});
+describe("processImage full pipeline (single format + blur)", () => {
+    bench("small image (200x150)", async () => {
+        await processImage(smallPng, root, resolveOptions({ formats: ["webp"] }), root);
+    });
+    bench("large image requiring downscale (2400x1600 -> 1920)", async () => {
+        await processImage(largePng, root, resolveOptions({ formats: ["webp"] }), root);
+    });
+});
+describe("processImage: blur enabled vs disabled overhead", () => {
+    bench("with blur placeholder", async () => {
+        await processImage(photoJpg, root, resolveOptions({ formats: ["webp"], blur: true }), root);
+    });
+    bench("without blur placeholder", async () => {
+        await processImage(photoJpg, root, resolveOptions({ formats: ["webp"], blur: false }), root);
+    });
+});

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

@@ -1,4 +1,10 @@
-import type { OptimizedImage, ResolvedBlurOptions, ResolvedOptions } from "./types.js";
+import type { ImageFormat, OptimizedImage, OptimizedImageSource, ResolvedBlurOptions, ResolvedOptions } from "./types.js";
+export declare function mimeTypeFor(format: ImageFormat | "original", originalSrc: string): string;
+/**
+ * <picture> tries <source> tags in document order, so sources must follow the
+ * user's own `formats` order (their priority) with "original" always last as fallback.
+ */
+export declare function sortSources(sources: OptimizedImageSource[], formats: ImageFormat[]): OptimizedImageSource[];
 export declare function toPublicSrc(absolutePath: string, publicRoot: string): string;
 export declare function toGeneratedPath(absolutePath: string, publicRoot: string, outDir: string, root: string): {
     targetFile: string;

package/dist/src/image_optimizer/process_image.js

@@ -2,6 +2,56 @@ import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import sharp from "sharp";
 import { resolveImageConfig } from "./types.js";
+const MIME_BY_FORMAT = {
+    avif: "image/avif",
+    webp: "image/webp",
+    png: "image/png",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    tiff: "image/tiff",
+    heif: "image/heif",
+    jp2: "image/jp2",
+    jxl: "image/jxl",
+};
+const MIME_BY_EXTENSION = {
+    ".avif": "image/avif",
+    ".webp": "image/webp",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".heif": "image/heif",
+    ".heic": "image/heif",
+    ".jp2": "image/jp2",
+    ".jxl": "image/jxl",
+};
+const EXTENSION_BY_FORMAT = {
+    avif: "avif",
+    webp: "webp",
+    png: "png",
+    jpeg: "jpg",
+    gif: "gif",
+    tiff: "tiff",
+    heif: "heif",
+    jp2: "jp2",
+    jxl: "jxl",
+};
+export function mimeTypeFor(format, originalSrc) {
+    if (format === "original") {
+        return MIME_BY_EXTENSION[path.extname(originalSrc).toLowerCase()] ?? "image/jpeg";
+    }
+    return MIME_BY_FORMAT[format];
+}
+/**
+ * <picture> tries <source> tags in document order, so sources must follow the
+ * user's own `formats` order (their priority) with "original" always last as fallback.
+ */
+export function sortSources(sources, formats) {
+    const priority = [...formats, "original"];
+    return [...sources].sort((a, b) => priority.indexOf(a.format) - priority.indexOf(b.format));
+}
 export function toPublicSrc(absolutePath, publicRoot) {
     const relative = path.relative(publicRoot, absolutePath);
     return `/${relative.split(path.sep).join("/")}`;
@@ -37,16 +87,46 @@ export async function makeBlurDataURL(targetFile, sourceWidth, sourceHeight, blu
         blurHeight,
     };
 }
-async function encodeSibling(targetFile, sourcePath, format, quality, maxWidth, needsResize) {
-    const target = targetFile.replace(/\.[^.]+$/, `.${format}`);
+async function encodeFormat(targetFile, sourcePath, format, quality, maxWidth, needsResize) {
     let pipeline = sharp(sourcePath);
     if (needsResize) {
         pipeline = pipeline.resize({ width: maxWidth });
     }
-    const encoded = format === "avif"
-        ? pipeline.avif({ quality })
-        : pipeline.webp({ quality });
-    await encoded.toFile(target);
+    let encoded;
+    if (format === "avif") {
+        encoded = pipeline.avif({ quality });
+    }
+    else if (format === "webp") {
+        encoded = pipeline.webp({ quality });
+    }
+    else if (format === "png") {
+        encoded = pipeline.png({ quality, compressionLevel: 9 });
+    }
+    else if (format === "jpeg") {
+        encoded = pipeline.jpeg({ quality, mozjpeg: true });
+    }
+    else if (format === "gif") {
+        encoded = pipeline.gif();
+    }
+    else if (format === "tiff") {
+        encoded = pipeline.tiff({ quality });
+    }
+    else if (format === "heif") {
+        encoded = pipeline.heif({ quality, compression: "hevc" });
+    }
+    else if (format === "jp2") {
+        encoded = pipeline.jp2({ quality });
+    }
+    else if (format === "jxl") {
+        encoded = pipeline.jxl({ quality });
+    }
+    else {
+        const ext = path.extname(sourcePath).toLowerCase();
+        encoded = ext === ".png"
+            ? pipeline.png({ quality, compressionLevel: 9 })
+            : pipeline.jpeg({ quality, mozjpeg: true });
+    }
+    await encoded.toFile(targetFile);
 }
 export async function processImage(absolutePath, publicRoot, options, root = path.dirname(publicRoot)) {
     const publicSrc = toPublicSrc(absolutePath, publicRoot);
@@ -61,25 +141,38 @@ export async function processImage(absolutePath, publicRoot, options, root = pat
         : sourceHeight;
     const { targetFile, targetSrc } = toGeneratedPath(absolutePath, publicRoot, options.outDir, root);
     await mkdir(path.dirname(targetFile), { recursive: true });
-    let pipeline = sharp(absolutePath);
-    if (needsResize) {
-        pipeline = pipeline.resize({ width: config.maxWidth });
-    }
-    const extension = path.extname(absolutePath).toLowerCase();
-    const encoded = extension === ".png"
-        ? pipeline.png({ quality: config.quality, compressionLevel: 9 })
-        : pipeline.jpeg({ quality: config.quality, mozjpeg: true });
-    await encoded.toFile(targetFile);
-    for (const format of config.formats) {
-        await encodeSibling(targetFile, absolutePath, format, config.quality, config.maxWidth, needsResize);
+    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 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);
+        sources.push({
+            format,
+            src: targetSrc.replace(/\.[^.]+$/, `.${ext}`),
+            type: mimeTypeFor(format, publicSrc),
+        });
     }
     let blurResult;
     if (config.blur.enabled) {
-        blurResult = await makeBlurDataURL(targetFile, width, height, config.blur);
+        blurResult = await makeBlurDataURL(primaryFile, width, height, config.blur);
     }
     return {
         originalSrc: publicSrc,
-        src: targetSrc,
+        src: primarySrc,
+        sources: sortSources(sources, config.formats),
         width,
         height,
         blurDataURL: blurResult?.blurDataURL,

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

@@ -1,3 +1,10 @@
-import type { OptimizedImage, ResolvedOptions } from "./types.js";
+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[];
+/**
+ * Merges optimizer overrides scanned from <Image> JSX props with the plugin's
+ * centralized `overrides` config, so settings can live at the usage site. An
+ * explicit config override for a given src still wins over a scanned one.
+ */
+export declare function mergeOverrides(scanned: Record<string, ImageOverrideOptions>, configured: Record<string, ImageOverrideOptions>): Record<string, ImageOverrideOptions>;
 export declare function run(root: string, options: ResolvedOptions, cacheFile?: string): Promise<OptimizedImage[]>;

package/dist/src/image_optimizer/run.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { isFresh, loadCache, saveCache } from "./cache.js";
 import { writeManifest } from "./manifest.js";
 import { processImage, toGeneratedPath, toPublicSrc } from "./process_image.js";
+import { collectUsedImageOverrides, collectUsedImages } from "./scan_used.js";
 import { resolveImageConfig, SUPPORTED_EXTENSIONS } from "./types.js";
 async function walk(directory, found) {
     let items;
@@ -30,35 +31,70 @@ export async function collectImages(dirs, root) {
     }
     return found.sort();
 }
-function targetAndSiblingPaths(absolutePath, publicRoot, options, root) {
+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);
-    const siblings = config.formats.map((format) => targetFile.replace(/\.[^.]+$/, `.${format}`));
-    const result = [targetFile, ...siblings];
+    const primaryFormat = config.formats.length > 0
+        ? config.formats[0]
+        : "original";
+    const primaryFile = primaryFormat === "original"
+        ? targetFile
+        : targetFile.replace(/\.[^.]+$/, `.${primaryFormat}`);
+    const result = [primaryFile];
+    for (let i = 1; i < config.formats.length; i++) {
+        const format = config.formats[i];
+        result.push(targetFile.replace(/\.[^.]+$/, `.${format}`));
+    }
     if (config.blur.enabled) {
-        result.push(targetFile.replace(/\.[^.]+$/, ".blur.webp"));
+        result.push(primaryFile.replace(/\.[^.]+$/, ".blur.webp"));
     }
     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
+ * explicit config override for a given src still wins over a scanned one.
+ */
+export function mergeOverrides(scanned, configured) {
+    const merged = { ...scanned };
+    for (const [src, override] of Object.entries(configured)) {
+        merged[src] = { ...merged[src], ...override };
+    }
+    return merged;
+}
 export async function run(root, options, cacheFile = path.resolve(root, options.cacheDir, "manifest.json")) {
     const publicRoot = path.resolve(root, "public");
     const manifestPath = path.resolve(root, options.manifest);
     const cache = await loadCache(cacheFile);
     const nextCache = {};
-    const files = await collectImages(options.dirs, root);
+    let files = [];
+    if (options.onlyUsed) {
+        files = await collectUsedImages(root, "public");
+        if (files.length === 0) {
+            files = await collectImages(options.dirs, root);
+        }
+    }
+    else {
+        files = await collectImages(options.dirs, root);
+    }
+    const scannedOverrides = await collectUsedImageOverrides(root, "public");
+    const resolvedOptions = {
+        ...options,
+        overrides: mergeOverrides(scannedOverrides, options.overrides),
+    };
     const entries = [];
     for (const file of files) {
         const relativeKey = path.relative(root, file);
         const cached = cache[relativeKey];
-        const targets = targetAndSiblingPaths(file, publicRoot, options, root);
+        const targets = targetAndSiblingPaths(file, publicRoot, resolvedOptions, root);
         const fresh = await isFresh(file, cached, targets);
         if (fresh && cached) {
             entries.push(cached.result);
             nextCache[relativeKey] = cached;
             continue;
         }
-        const result = await processImage(file, publicRoot, options, root);
+        const result = await processImage(file, publicRoot, resolvedOptions, root);
         const fileStat = await stat(file);
         entries.push(result);
         nextCache[relativeKey] = {

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

@@ -0,0 +1,19 @@
+import type { ImageOverrideOptions } from "./types.js";
+export declare const CODE_EXTENSIONS: readonly string[];
+export declare const IGNORED_DIRS: ReadonlySet<string>;
+export declare function findCodeFiles(dir: string, found?: string[]): Promise<string[]>;
+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.
+ */
+export declare function extractImageOverrides(code: string): Record<string, ImageOverrideOptions>;
+/**
+ * Scans project source for <Image> tags with per-image optimizer props
+ * (formats / blur / quality / maxWidth) and returns them keyed by public src,
+ * in the same shape as the plugin's `overrides` config option.
+ */
+export declare function collectUsedImageOverrides(root: string, publicDir?: string): Promise<Record<string, ImageOverrideOptions>>;
+export declare function collectUsedImages(root: string, publicDir?: string): Promise<string[]>;

package/dist/src/image_optimizer/scan_used.js

@@ -0,0 +1,229 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+export const CODE_EXTENSIONS = [
+    ".tsx",
+    ".ts",
+    ".jsx",
+    ".js",
+    ".mjs",
+    ".cjs",
+    ".astro",
+    ".vue",
+    ".svelte",
+    ".mdx",
+    ".html",
+];
+export const IGNORED_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    ".vinext",
+    "dist",
+    "build",
+    "coverage",
+    ".cache",
+    ".skeleton-diff",
+    "generated",
+]);
+export async function findCodeFiles(dir, found = []) {
+    let items;
+    try {
+        items = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return found;
+    }
+    for (const item of items) {
+        if (IGNORED_DIRS.has(item.name))
+            continue;
+        const full = path.join(dir, item.name);
+        if (item.isDirectory()) {
+            await findCodeFiles(full, found);
+        }
+        else if (CODE_EXTENSIONS.includes(path.extname(item.name).toLowerCase())) {
+            found.push(full);
+        }
+    }
+    return found;
+}
+export function extractImageReferences(code) {
+    const refs = new Set();
+    const pattern = /(?:["'`])([^"'`\s\n\r#?]+\.(?:png|jpg|jpeg|webp|avif))(?:\?[^"'`\s]*|#[^"'`\s]*)?(?:["'`])/gi;
+    let match;
+    while ((match = pattern.exec(code)) !== null) {
+        const raw = match[1];
+        if (raw)
+            refs.add(raw);
+    }
+    return Array.from(refs);
+}
+const IMAGE_FORMATS = [
+    "avif", "webp", "png", "jpeg", "gif", "tiff", "heif", "jp2", "jxl",
+];
+function parseFormatsAttr(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "false")
+        return false;
+    const values = trimmed.match(/[a-z0-9]+/gi) ?? [];
+    const formats = values
+        .map((v) => v.toLowerCase())
+        .filter((v) => IMAGE_FORMATS.includes(v));
+    return formats.length > 0 ? formats : undefined;
+}
+function parseNumberAttr(raw) {
+    const value = Number(raw.trim().replace(/[{}]/g, ""));
+    return Number.isFinite(value) ? value : undefined;
+}
+function parseBlurAttr(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "false")
+        return false;
+    if (trimmed === "true")
+        return true;
+    const blur = {};
+    const size = trimmed.match(/size\s*:\s*(\d+)/);
+    const quality = trimmed.match(/quality\s*:\s*(\d+)/);
+    const stdDeviation = trimmed.match(/stdDeviation\s*:\s*(\d+)/);
+    if (size)
+        blur.size = Number(size[1]);
+    if (quality)
+        blur.quality = Number(quality[1]);
+    if (stdDeviation)
+        blur.stdDeviation = Number(stdDeviation[1]);
+    return Object.keys(blur).length > 0 ? blur : undefined;
+}
+/**
+ * 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.
+ */
+export function extractImageOverrides(code) {
+    const overrides = {};
+    const tagPattern = /<Image\b([^>]*)\/?>/gs;
+    let tagMatch;
+    while ((tagMatch = tagPattern.exec(code)) !== null) {
+        const attrs = tagMatch[1];
+        const srcMatch = attrs.match(/\bsrc\s*=\s*(?:["'`]([^"'`]+)["'`]|\{["'`]([^"'`]+)["'`]\})/);
+        if (!srcMatch)
+            continue;
+        const src = (srcMatch[1] ?? srcMatch[2]).split("?")[0].split("#")[0];
+        const override = {};
+        const formatsMatch = attrs.match(/\bformats\s*=\s*\{([^}]*)\}/);
+        if (formatsMatch) {
+            const parsed = parseFormatsAttr(formatsMatch[1]);
+            if (parsed !== undefined)
+                override.formats = parsed;
+        }
+        const maxWidthMatch = attrs.match(/\bmaxWidth\s*=\s*\{([^}]*)\}/);
+        if (maxWidthMatch) {
+            const trimmed = maxWidthMatch[1].trim();
+            const parsed = trimmed === "false" ? false : parseNumberAttr(trimmed);
+            if (parsed !== undefined)
+                override.maxWidth = parsed;
+        }
+        const qualityMatch = attrs.match(/\bquality\s*=\s*\{?(\d+)\}?/);
+        if (qualityMatch) {
+            override.quality = Number(qualityMatch[1]);
+        }
+        const blurMatch = attrs.match(/\bblur\s*=\s*\{([^}]*)\}/);
+        if (blurMatch) {
+            const parsed = parseBlurAttr(blurMatch[1]);
+            if (parsed !== undefined)
+                override.blur = parsed;
+        }
+        if (Object.keys(override).length > 0) {
+            overrides[src] = { ...overrides[src], ...override };
+        }
+    }
+    return overrides;
+}
+async function collectCodeFiles(root, publicDir) {
+    let rootItems;
+    try {
+        rootItems = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const codeFiles = [];
+    for (const item of rootItems) {
+        if (IGNORED_DIRS.has(item.name))
+            continue;
+        if (item.name === publicDir)
+            continue;
+        const full = path.join(root, item.name);
+        if (item.isDirectory()) {
+            await findCodeFiles(full, codeFiles);
+        }
+        else if (CODE_EXTENSIONS.includes(path.extname(item.name).toLowerCase())) {
+            codeFiles.push(full);
+        }
+    }
+    return codeFiles;
+}
+function resolvePublicSrc(ref) {
+    const cleanRef = ref.split("?")[0].split("#")[0];
+    let relative = cleanRef;
+    if (relative.startsWith("/"))
+        relative = relative.slice(1);
+    if (relative.startsWith("public/"))
+        relative = relative.slice("public/".length);
+    return `/${relative}`;
+}
+/**
+ * Scans project source for <Image> tags with per-image optimizer props
+ * (formats / blur / quality / maxWidth) and returns them keyed by public src,
+ * in the same shape as the plugin's `overrides` config option.
+ */
+export async function collectUsedImageOverrides(root, publicDir = "public") {
+    const codeFiles = await collectCodeFiles(root, publicDir);
+    const overrides = {};
+    for (const file of codeFiles) {
+        const content = await readFile(file, "utf8").catch(() => "");
+        const fileOverrides = extractImageOverrides(content);
+        for (const [src, override] of Object.entries(fileOverrides)) {
+            const publicSrc = resolvePublicSrc(src);
+            overrides[publicSrc] = { ...overrides[publicSrc], ...override };
+        }
+    }
+    return overrides;
+}
+export async function collectUsedImages(root, publicDir = "public") {
+    const publicRoot = path.resolve(root, publicDir);
+    const codeFiles = await collectCodeFiles(root, publicDir);
+    const referenced = new Set();
+    for (const file of codeFiles) {
+        const content = await readFile(file, "utf8").catch(() => "");
+        const refs = extractImageReferences(content);
+        for (const ref of refs) {
+            referenced.add(ref);
+        }
+    }
+    const resolvedFiles = new Set();
+    for (const ref of referenced) {
+        const cleanRef = ref.split("?")[0].split("#")[0];
+        let relativeInPublic = cleanRef;
+        if (relativeInPublic.startsWith("/"))
+            relativeInPublic = relativeInPublic.slice(1);
+        if (relativeInPublic.startsWith("public/"))
+            relativeInPublic = relativeInPublic.slice("public/".length);
+        const candidate = path.resolve(publicRoot, relativeInPublic);
+        if (candidate.startsWith(publicRoot)) {
+            resolvedFiles.add(candidate);
+        }
+    }
+    const existing = [];
+    for (const file of resolvedFiles) {
+        try {
+            const fileStat = await stat(file);
+            if (fileStat.isFile()) {
+                existing.push(file);
+            }
+        }
+        catch {
+            // does not exist, ignore
+        }
+    }
+    return existing.sort();
+}

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

@@ -1,4 +1,4 @@
-export type ImageFormat = "avif" | "webp";
+export type ImageFormat = "avif" | "webp" | "png" | "jpeg" | "gif" | "tiff" | "heif" | "jp2" | "jxl";
 export interface ImageBlurOptions {
     /** Enable blur placeholder generation. Default: true */
     enabled?: boolean;
@@ -22,7 +22,7 @@ export interface ImageOverrideOptions {
 export interface ImageOptimizerPluginOptions {
     /** Enable or disable image optimization. Default: true */
     enabled?: boolean;
-    /** Directories scanned recursively relative to project root. Default: ["public/images", "public/icons"] */
+    /** Directories scanned recursively relative to project root when onlyUsed is false. Default: ["public/images", "public/icons"] */
     dirs?: string[];
     /** Target directory for optimized assets. Default: "public/generated" */
     outDir?: string;
@@ -30,7 +30,7 @@ export interface ImageOptimizerPluginOptions {
     maxWidth?: number | false;
     /** Compression quality for rasters. Default: 80 */
     quality?: number;
-    /** Target sibling formats, or `false` to disable format conversions. Default: ["avif", "webp"] */
+    /** Target sibling formats, or `false` to disable format conversions. Default: ["webp"] */
     formats?: ImageFormat[] | false;
     /** Output path for generated JSON manifest. Default: "public/generated/images.json" */
     manifest?: string;
@@ -40,6 +40,8 @@ export interface ImageOptimizerPluginOptions {
     dev?: boolean;
     /** Cache directory. Default: "node_modules/.cache/cloudflare-next-intl/image-optimizer" */
     cacheDir?: string;
+    /** Scan code files and optimize ONLY images actually referenced in <Image>. Default: true */
+    onlyUsed?: boolean;
     /** Per-image overrides keyed by public src (e.g. `"/images/hero.png"`) */
     overrides?: Record<string, ImageOverrideOptions>;
 }
@@ -60,6 +62,7 @@ export interface ResolvedOptions {
     blur: ResolvedBlurOptions;
     dev: boolean;
     cacheDir: string;
+    onlyUsed: boolean;
     overrides: Record<string, ImageOverrideOptions>;
 }
 export interface ResolvedImageConfig {
@@ -68,9 +71,15 @@ export interface ResolvedImageConfig {
     formats: ImageFormat[];
     blur: ResolvedBlurOptions;
 }
+export interface OptimizedImageSource {
+    format: ImageFormat | "original";
+    src: string;
+    type: string;
+}
 export interface OptimizedImage {
     originalSrc: string;
     src: string;
+    sources?: OptimizedImageSource[];
     width: number;
     height: number;
     blurDataURL?: string;

package/dist/src/image_optimizer/types.js

@@ -1,4 +1,4 @@
-export const SUPPORTED_EXTENSIONS = [".png", ".jpg", ".jpeg"];
+export const SUPPORTED_EXTENSIONS = [".png", ".jpg", ".jpeg", ".webp", ".avif"];
 export const DEFAULT_BLUR_OPTIONS = {
     enabled: true,
     size: 8,
@@ -11,11 +11,12 @@ export const DEFAULT_OPTIONS = {
     outDir: "public/generated",
     maxWidth: 1920,
     quality: 80,
-    formats: ["avif", "webp"],
+    formats: ["webp"],
     manifest: "public/generated/images.json",
     blur: DEFAULT_BLUR_OPTIONS,
     dev: true,
     cacheDir: "node_modules/.cache/cloudflare-next-intl/image-optimizer",
+    onlyUsed: true,
     overrides: {},
 };
 export function resolveBlurOptions(blur, parentDefault = DEFAULT_BLUR_OPTIONS) {
@@ -51,6 +52,7 @@ export function resolveOptions(options) {
         blur,
         dev: raw.dev ?? DEFAULT_OPTIONS.dev,
         cacheDir: raw.cacheDir ?? DEFAULT_OPTIONS.cacheDir,
+        onlyUsed: raw.onlyUsed ?? DEFAULT_OPTIONS.onlyUsed,
         overrides: raw.overrides ? { ...raw.overrides } : {},
     };
 }

package/dist/src/index.d.ts

@@ -4,3 +4,4 @@ export * from './server';
 export * from './client';
 export * from './theme_switcher';
 export * from './types';
+export { default as Image, getImageProps, getImageBlurSvg } from './image_optimizer/next_image_shim';

package/dist/src/index.js

@@ -4,3 +4,4 @@ export * from './server';
 export * from './client';
 export * from './theme_switcher';
 export * from './types';
+export { default as Image, getImageProps, getImageBlurSvg } from './image_optimizer/next_image_shim';

package/dist/src/test_utils/image_optimizer_test_helpers.d.ts

@@ -0,0 +1,4 @@
+export declare function makeTempDir(): Promise<string>;
+export declare function cleanup(dir: string): Promise<void>;
+export declare function writeFixturePng(dir: string, filename: string, width: number, height: number): Promise<string>;
+export declare function writeFixtureJpg(dir: string, filename: string, width: number, height: number): Promise<string>;

package/dist/src/test_utils/image_optimizer_test_helpers.js

@@ -0,0 +1,40 @@
+import { mkdtemp, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import sharp from "sharp";
+export async function makeTempDir() {
+    return mkdtemp(path.join(tmpdir(), "cfni-img-test-"));
+}
+export async function cleanup(dir) {
+    await rm(dir, { recursive: true, force: true });
+}
+export async function writeFixturePng(dir, filename, width, height) {
+    await mkdir(dir, { recursive: true });
+    const target = path.join(dir, filename);
+    await sharp({
+        create: {
+            width,
+            height,
+            channels: 4,
+            background: { r: 120, g: 180, b: 240, alpha: 1 },
+        },
+    })
+        .png()
+        .toFile(target);
+    return target;
+}
+export async function writeFixtureJpg(dir, filename, width, height) {
+    await mkdir(dir, { recursive: true });
+    const target = path.join(dir, filename);
+    await sharp({
+        create: {
+            width,
+            height,
+            channels: 3,
+            background: { r: 240, g: 120, b: 180 },
+        },
+    })
+        .jpeg()
+        .toFile(target);
+    return target;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.8.56",
+  "version": "0.8.57",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,6 +25,14 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./image": {
+      "types": "./dist/src/image.d.ts",
+      "import": "./dist/src/image.js"
+    },
+    "./Image": {
+      "types": "./dist/src/image.d.ts",
+      "import": "./dist/src/image.js"
+    },
     "./client": {
       "types": "./dist/src/client/index.d.ts",
       "import": "./dist/src/client/index.js"