cloudflare-next-intl 0.8.53 → 0.8.55

package/README.md

@@ -256,10 +256,11 @@ export default defineConfig({
 ```
 
 ##### What `cloudflareNextIntl()` Does
-1. **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.
-2. **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).
-3. **Cloudflare Workers Client Stub (`cfWorkersClientStub`)**: Stubs `cloudflare:workers` in client builds so shared modules can be referenced without client bundling errors.
-4. **Build ID Asset Emission (`buildIdAsset`)**: Emits `BUILD_ID` static asset in the client build directory from `process.env.__VINEXT_SHARED_BUILD_ID` or `process.env.__VINEXT_BUILD_ID`.
+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.
+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.
+5. **Build ID Asset Emission (`buildIdAsset`)**: Emits `BUILD_ID` static asset in the client build directory from `process.env.__VINEXT_SHARED_BUILD_ID` or `process.env.__VINEXT_BUILD_ID`.
 
 ##### Plugin Options
 All features are enabled by default, and can be individually configured or toggled off:
@@ -271,6 +272,16 @@ import { cloudflareNextIntl } from "cloudflare-next-intl/vite";
 export default defineConfig({
     plugins: [
         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`)
+                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
+                    "/images/hero.png": { maxWidth: false, formats: ["webp"], blur: { quality: 80 } },
+                    "/images/logo.png": { formats: false, blur: false },
+                },
+            },
             messagesDir: "./messages",            // Path to locale JSON files (default: './messages')
             intlConfigPath: "./src/l18n/intl_config.ts", // Path to intl config (auto-detected if omitted)
             buildIdAsset: true,                   // Emit BUILD_ID asset (or custom string filename, default: true)
@@ -283,7 +294,7 @@ export default defineConfig({
 ```
 
 Individual standalone plugins are also exported if you only need a specific feature:
-`buildIdAsset`, `localeFilePlugin`, `userAgentStubPlugin`, `cfWorkersClientStubPlugin`.
+`imageOptimizerPlugin` (or `imageOptimizer`), `buildIdAsset`, `localeFilePlugin`, `userAgentStubPlugin`, `cfWorkersClientStubPlugin`.
 
 ```tsx
 // Client Components ("use client")

package/bin/image_optimizer.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import path from "node:path";
+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 cacheFile = path.resolve(root, options.cacheDir, "manifest.json");
+
+console.log("[cfni-image-optimizer] scanning 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_optimizer/blur_svg.d.ts

@@ -0,0 +1 @@
+export declare function getImageBlurSvg(blurDataURL: string, blurWidth?: number, blurHeight?: number, objectFit?: string, stdDeviation?: number): string;

package/dist/src/image_optimizer/blur_svg.js

@@ -0,0 +1,16 @@
+export function getImageBlurSvg(blurDataURL, blurWidth, blurHeight, objectFit, stdDeviation = 20) {
+    const std = stdDeviation;
+    const viewBox = blurWidth && blurHeight
+        ? `viewBox='0 0 ${blurWidth * 40} ${blurHeight * 40}'`
+        : "";
+    const preserveAspectRatio = viewBox
+        ? "none"
+        : objectFit === "contain"
+            ? "xMidYMid"
+            : objectFit === "cover"
+                ? "xMidYMid slice"
+                : "none";
+    const svg = `<svg xmlns='http://www.w3.org/2000/svg' ${viewBox}><filter id='b' color-interpolation-filters='sRGB'><feGaussianBlur stdDeviation='${std}'/><feColorMatrix values='1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 100 -1' result='s'/><feFlood x='0' y='0' width='100%' height='100%'/><feComposite operator='out' in='s'/><feComposite in2='SourceGraphic'/><feGaussianBlur stdDeviation='${std}'/></filter><image width='100%' height='100%' x='0' y='0' preserveAspectRatio='${preserveAspectRatio}' style='filter: url(#b);' href='${blurDataURL}'/></svg>`;
+    const base64 = Buffer.from(svg).toString("base64");
+    return `data:image/svg+xml;base64,${base64}`;
+}

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

@@ -0,0 +1,10 @@
+import type { OptimizedImage } from "./types.js";
+export interface CacheEntry {
+    mtimeMs: number;
+    size: number;
+    result: OptimizedImage;
+}
+export type CacheData = Record<string, CacheEntry>;
+export declare function isFresh(sourcePath: string, cached: CacheEntry | undefined, targets: string[]): Promise<boolean>;
+export declare function loadCache(cacheFile: string): Promise<CacheData>;
+export declare function saveCache(cacheFile: string, data: CacheData): Promise<void>;

package/dist/src/image_optimizer/cache.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+export async function isFresh(sourcePath, cached, targets) {
+    if (!cached)
+        return false;
+    try {
+        const stats = await stat(sourcePath);
+        if (stats.mtimeMs !== cached.mtimeMs || stats.size !== cached.size) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    for (const target of targets) {
+        if (!existsSync(target))
+            return false;
+    }
+    return true;
+}
+export async function loadCache(cacheFile) {
+    try {
+        const content = await readFile(cacheFile, "utf8");
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+export async function saveCache(cacheFile, data) {
+    await mkdir(path.dirname(cacheFile), { recursive: true });
+    await writeFile(cacheFile, JSON.stringify(data, null, 2), "utf8");
+}

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

@@ -0,0 +1,8 @@
+export { imageOptimizerPlugin, imageOptimizer, VIRTUAL_IMAGE_SHIM_ID, default, } from "./plugin.js";
+export { resolveOptions, resolveImageConfig, resolveBlurOptions, DEFAULT_OPTIONS, DEFAULT_BLUR_OPTIONS, SUPPORTED_EXTENSIONS, type ImageFormat, type ImageBlurOptions, type ImageOverrideOptions, type ImageOptimizerPluginOptions, type ResolvedBlurOptions, type ResolvedOptions, type ResolvedImageConfig, type OptimizedImage, type ManifestData, } from "./types.js";
+export { processImage, makeBlurDataURL, toGeneratedPath, toPublicSrc, } from "./process_image.js";
+export { renderManifest, writeManifest, } from "./manifest.js";
+export { isFresh, loadCache, saveCache, type CacheEntry, type CacheData, } from "./cache.js";
+export { collectImages, run, } from "./run.js";
+export { getImageBlurSvg, } from "./blur_svg.js";
+export { type ManifestEntry, } from "./next_image_shim.js";

package/dist/src/image_optimizer/index.js

@@ -0,0 +1,7 @@
+export { imageOptimizerPlugin, imageOptimizer, VIRTUAL_IMAGE_SHIM_ID, default, } from "./plugin.js";
+export { resolveOptions, resolveImageConfig, resolveBlurOptions, DEFAULT_OPTIONS, DEFAULT_BLUR_OPTIONS, SUPPORTED_EXTENSIONS, } from "./types.js";
+export { processImage, makeBlurDataURL, toGeneratedPath, toPublicSrc, } from "./process_image.js";
+export { renderManifest, writeManifest, } from "./manifest.js";
+export { isFresh, loadCache, saveCache, } from "./cache.js";
+export { collectImages, run, } from "./run.js";
+export { getImageBlurSvg, } from "./blur_svg.js";

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

@@ -0,0 +1,3 @@
+import type { OptimizedImage } from "./types.js";
+export declare function renderManifest(entries: OptimizedImage[]): string;
+export declare function writeManifest(manifestPath: string, entries: OptimizedImage[]): Promise<void>;

package/dist/src/image_optimizer/manifest.js

@@ -0,0 +1,25 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export function renderManifest(entries) {
+    const images = {};
+    const sorted = [...entries].sort((a, b) => a.originalSrc.localeCompare(b.originalSrc));
+    for (const entry of sorted) {
+        images[entry.originalSrc] = entry;
+    }
+    const manifest = { images };
+    return JSON.stringify(manifest, null, 2);
+}
+export async function writeManifest(manifestPath, entries) {
+    const rendered = renderManifest(entries);
+    let current = "";
+    try {
+        current = await readFile(manifestPath, "utf8");
+    }
+    catch {
+        // file does not exist yet
+    }
+    if (current === rendered)
+        return;
+    await mkdir(path.dirname(manifestPath), { recursive: true });
+    await writeFile(manifestPath, rendered, "utf8");
+}

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

@@ -0,0 +1,9 @@
+import React from "react";
+import { getImageProps as nextGetImageProps } from "next/image";
+import type { ImageProps } from "next/image";
+import { getImageBlurSvg } from "./blur_svg.js";
+import type { OptimizedImage } from "./types.js";
+export type ManifestEntry = OptimizedImage;
+export default function Image(props: ImageProps): React.JSX.Element;
+export declare function getImageProps(props: ImageProps): ReturnType<typeof nextGetImageProps>;
+export { getImageBlurSvg };

package/dist/src/image_optimizer/next_image_shim.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } 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";
+const manifestData = manifest;
+const images = (manifestData && typeof manifestData === "object" && manifestData.images)
+    ? manifestData.images
+    : {};
+function resolveProps(props) {
+    let src = props.src;
+    let blurDataURL = props.blurDataURL;
+    let width = props.width;
+    let height = props.height;
+    if (typeof src === "string") {
+        const entry = images[src];
+        if (entry) {
+            if (entry.src)
+                src = entry.src;
+            if (!blurDataURL && props.placeholder === "blur" && entry.blurDataURL) {
+                blurDataURL = getImageBlurSvg(entry.blurDataURL, entry.blurWidth, entry.blurHeight, props.style?.objectFit);
+            }
+            if (!width && !props.fill && entry.width) {
+                width = entry.width;
+                height = entry.height;
+            }
+        }
+    }
+    return { ...props, src, blurDataURL, width, height };
+}
+export default function Image(props) {
+    const resolved = resolveProps(props);
+    return _jsx(NextImage, { ...resolved });
+}
+export function getImageProps(props) {
+    const resolved = resolveProps(props);
+    return nextGetImageProps(resolved);
+}
+export { getImageBlurSvg };

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

@@ -0,0 +1,8 @@
+import type { Plugin } from "vite";
+import type { ImageOptimizerPluginOptions } from "./types.js";
+export declare const VIRTUAL_IMAGE_SHIM_ID = "virtual:cloudflare-next-intl-image";
+export declare const VIRTUAL_MANIFEST_ID = "virtual:cloudflare-next-intl-images-manifest";
+export declare function getShimPath(dir?: string): string;
+export declare function imageOptimizerPlugin(options?: ImageOptimizerPluginOptions): Plugin;
+export declare const imageOptimizer: typeof imageOptimizerPlugin;
+export default imageOptimizerPlugin;

package/dist/src/image_optimizer/plugin.js

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { run } from "./run.js";
+import { resolveOptions } from "./types.js";
+export const VIRTUAL_IMAGE_SHIM_ID = "virtual:cloudflare-next-intl-image";
+export const VIRTUAL_MANIFEST_ID = "virtual:cloudflare-next-intl-images-manifest";
+const RESOLVED_MANIFEST_ID = "\0" + VIRTUAL_MANIFEST_ID;
+export function getShimPath(dir = path.dirname(fileURLToPath(import.meta.url))) {
+    const jsPath = path.join(dir, "next_image_shim.js");
+    if (existsSync(jsPath))
+        return jsPath;
+    return path.join(dir, "next_image_shim.tsx");
+}
+export function imageOptimizerPlugin(options) {
+    const resolved = resolveOptions(options);
+    return {
+        name: "cloudflare-next-intl-image-optimizer",
+        enforce: "pre",
+        apply: resolved.dev ? undefined : "build",
+        resolveId(id) {
+            if (id === VIRTUAL_IMAGE_SHIM_ID) {
+                return getShimPath();
+            }
+            if (id === VIRTUAL_MANIFEST_ID) {
+                return RESOLVED_MANIFEST_ID;
+            }
+            return undefined;
+        },
+        load(id) {
+            if (id === RESOLVED_MANIFEST_ID) {
+                const manifestPath = path.resolve(process.cwd(), resolved.manifest);
+                if (existsSync(manifestPath)) {
+                    const content = readFileSync(manifestPath, "utf8");
+                    return `export default ${content};`;
+                }
+                return `export default { images: {} };`;
+            }
+            return undefined;
+        },
+        transform(code, id) {
+            if (!resolved.enabled)
+                return undefined;
+            if (id.includes("node_modules"))
+                return undefined;
+            if (id === getShimPath())
+                return undefined;
+            if (!/from\s*["']next\/image["']/.test(code))
+                return undefined;
+            const next = code.replace(/(import\s+(?!type\s)[^;]*?from\s*)(["'])next\/image\2/g, `$1$2${VIRTUAL_IMAGE_SHIM_ID}$2`);
+            return next === code ? undefined : { code: next, map: null };
+        },
+        async buildStart() {
+            if (!resolved.enabled)
+                return;
+            const root = process.cwd();
+            const cacheFile = path.resolve(root, resolved.cacheDir, "manifest.json");
+            const entries = await run(root, resolved, cacheFile);
+            this.info?.(`[cloudflare-next-intl] image-optimizer: ${entries.length} images in ${resolved.manifest}`);
+        },
+    };
+}
+export const imageOptimizer = imageOptimizerPlugin;
+export default imageOptimizerPlugin;

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

@@ -0,0 +1,12 @@
+import type { OptimizedImage, ResolvedBlurOptions, ResolvedOptions } from "./types.js";
+export declare function toPublicSrc(absolutePath: string, publicRoot: string): string;
+export declare function toGeneratedPath(absolutePath: string, publicRoot: string, outDir: string, root: string): {
+    targetFile: string;
+    targetSrc: string;
+};
+export declare function makeBlurDataURL(targetFile: string, sourceWidth: number, sourceHeight: number, blurOptions: ResolvedBlurOptions): Promise<{
+    blurDataURL: string;
+    blurWidth: number;
+    blurHeight: number;
+}>;
+export declare function processImage(absolutePath: string, publicRoot: string, options: ResolvedOptions, root?: string): Promise<OptimizedImage>;

package/dist/src/image_optimizer/process_image.js

@@ -0,0 +1,89 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import sharp from "sharp";
+import { resolveImageConfig } from "./types.js";
+export function toPublicSrc(absolutePath, publicRoot) {
+    const relative = path.relative(publicRoot, absolutePath);
+    return `/${relative.split(path.sep).join("/")}`;
+}
+export function toGeneratedPath(absolutePath, publicRoot, outDir, root) {
+    const relative = path.relative(publicRoot, absolutePath);
+    const resolvedOutDir = path.resolve(root, outDir);
+    const targetFile = path.join(resolvedOutDir, relative);
+    const outDirRelativePublic = path.relative(publicRoot, resolvedOutDir);
+    const targetSrc = `/${path.join(outDirRelativePublic, relative).split(path.sep).join("/")}`;
+    return { targetFile, targetSrc };
+}
+export async function makeBlurDataURL(targetFile, sourceWidth, sourceHeight, blurOptions) {
+    const blurFile = targetFile.replace(/\.[^.]+$/, ".blur.webp");
+    let blurWidth;
+    let blurHeight;
+    if (sourceWidth >= sourceHeight) {
+        blurWidth = blurOptions.size;
+        blurHeight = Math.max(Math.round((sourceHeight / sourceWidth) * blurOptions.size), 1);
+    }
+    else {
+        blurWidth = Math.max(Math.round((sourceWidth / sourceHeight) * blurOptions.size), 1);
+        blurHeight = blurOptions.size;
+    }
+    const buffer = await sharp(targetFile)
+        .resize({ width: blurWidth, height: blurHeight, fit: "inside" })
+        .webp({ quality: blurOptions.quality })
+        .toBuffer();
+    await sharp(buffer).toFile(blurFile);
+    return {
+        blurDataURL: `data:image/webp;base64,${buffer.toString("base64")}`,
+        blurWidth,
+        blurHeight,
+    };
+}
+async function encodeSibling(targetFile, sourcePath, format, quality, maxWidth, needsResize) {
+    const target = targetFile.replace(/\.[^.]+$/, `.${format}`);
+    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);
+}
+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 });
+    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);
+    }
+    let blurResult;
+    if (config.blur.enabled) {
+        blurResult = await makeBlurDataURL(targetFile, width, height, config.blur);
+    }
+    return {
+        originalSrc: publicSrc,
+        src: targetSrc,
+        width,
+        height,
+        blurDataURL: blurResult?.blurDataURL,
+        blurWidth: blurResult?.blurWidth,
+        blurHeight: blurResult?.blurHeight,
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { OptimizedImage, ResolvedOptions } from "./types.js";
+export declare function collectImages(dirs: string[], root: string): Promise<string[]>;
+export declare function run(root: string, options: ResolvedOptions, cacheFile?: string): Promise<OptimizedImage[]>;

package/dist/src/image_optimizer/run.js

@@ -0,0 +1,73 @@
+import { readdir, stat } from "node:fs/promises";
+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 { resolveImageConfig, SUPPORTED_EXTENSIONS } from "./types.js";
+async function walk(directory, found) {
+    let items;
+    try {
+        items = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const item of items) {
+        const full = path.join(directory, item.name);
+        if (item.isDirectory()) {
+            await walk(full, found);
+            continue;
+        }
+        if (SUPPORTED_EXTENSIONS.includes(path.extname(item.name).toLowerCase())) {
+            found.push(full);
+        }
+    }
+}
+export async function collectImages(dirs, root) {
+    const found = [];
+    for (const dir of dirs) {
+        await walk(path.resolve(root, dir), found);
+    }
+    return found.sort();
+}
+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];
+    if (config.blur.enabled) {
+        result.push(targetFile.replace(/\.[^.]+$/, ".blur.webp"));
+    }
+    return result;
+}
+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);
+    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 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 fileStat = await stat(file);
+        entries.push(result);
+        nextCache[relativeKey] = {
+            mtimeMs: fileStat.mtimeMs,
+            size: fileStat.size,
+            result,
+        };
+    }
+    await saveCache(cacheFile, nextCache);
+    await writeManifest(manifestPath, entries);
+    return entries;
+}

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

@@ -0,0 +1,3 @@
+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>;

package/dist/src/image_optimizer/test_helpers.js

@@ -0,0 +1,25 @@
+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;
+}

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

@@ -0,0 +1,88 @@
+export type ImageFormat = "avif" | "webp";
+export interface ImageBlurOptions {
+    /** Enable blur placeholder generation. Default: true */
+    enabled?: boolean;
+    /** Tiny thumbnail dimension (largest side). Default: 8 */
+    size?: number;
+    /** WebP thumbnail quality. Default: 70 */
+    quality?: number;
+    /** Gaussian blur stdDeviation for SVG filter. Default: 20 */
+    stdDeviation?: number;
+}
+export interface ImageOverrideOptions {
+    /** Formats to emit for this image, or `false` to disable format conversions. Default: inherits global */
+    formats?: ImageFormat[] | false;
+    /** Max width to downscale, or `false` to preserve original dimensions. Default: inherits global */
+    maxWidth?: number | false;
+    /** Compression quality (1-100). Default: inherits global */
+    quality?: number;
+    /** Blur placeholder settings for this image, or `false` to disable. Default: inherits global */
+    blur?: boolean | ImageBlurOptions;
+}
+export interface ImageOptimizerPluginOptions {
+    /** Enable or disable image optimization. Default: true */
+    enabled?: boolean;
+    /** Directories scanned recursively relative to project root. Default: ["public/images", "public/icons"] */
+    dirs?: string[];
+    /** Target directory for optimized assets. Default: "public/generated" */
+    outDir?: string;
+    /** Max width to downscale oversized images, or `false` to disable. Default: 1920 */
+    maxWidth?: number | false;
+    /** Compression quality for rasters. Default: 80 */
+    quality?: number;
+    /** Target sibling formats, or `false` to disable format conversions. Default: ["avif", "webp"] */
+    formats?: ImageFormat[] | false;
+    /** Output path for generated JSON manifest. Default: "public/generated/images.json" */
+    manifest?: string;
+    /** Global blur placeholder settings, or `false` to disable blur generation. Default: true */
+    blur?: boolean | ImageBlurOptions;
+    /** Run on dev server as well as production build. Default: true */
+    dev?: boolean;
+    /** Cache directory. Default: "node_modules/.cache/cloudflare-next-intl/image-optimizer" */
+    cacheDir?: string;
+    /** Per-image overrides keyed by public src (e.g. `"/images/hero.png"`) */
+    overrides?: Record<string, ImageOverrideOptions>;
+}
+export interface ResolvedBlurOptions {
+    enabled: boolean;
+    size: number;
+    quality: number;
+    stdDeviation: number;
+}
+export interface ResolvedOptions {
+    enabled: boolean;
+    dirs: string[];
+    outDir: string;
+    maxWidth: number | false;
+    quality: number;
+    formats: ImageFormat[];
+    manifest: string;
+    blur: ResolvedBlurOptions;
+    dev: boolean;
+    cacheDir: string;
+    overrides: Record<string, ImageOverrideOptions>;
+}
+export interface ResolvedImageConfig {
+    maxWidth: number | false;
+    quality: number;
+    formats: ImageFormat[];
+    blur: ResolvedBlurOptions;
+}
+export interface OptimizedImage {
+    originalSrc: string;
+    src: string;
+    width: number;
+    height: number;
+    blurDataURL?: string;
+    blurWidth?: number;
+    blurHeight?: number;
+}
+export interface ManifestData {
+    images: Record<string, OptimizedImage>;
+}
+export declare const SUPPORTED_EXTENSIONS: readonly string[];
+export declare const DEFAULT_BLUR_OPTIONS: ResolvedBlurOptions;
+export declare const DEFAULT_OPTIONS: ResolvedOptions;
+export declare function resolveBlurOptions(blur: boolean | ImageBlurOptions | undefined, parentDefault?: ResolvedBlurOptions): ResolvedBlurOptions;
+export declare function resolveOptions(options: ImageOptimizerPluginOptions | undefined): ResolvedOptions;
+export declare function resolveImageConfig(publicSrc: string, options: ResolvedOptions): ResolvedImageConfig;

package/dist/src/image_optimizer/types.js

@@ -0,0 +1,82 @@
+export const SUPPORTED_EXTENSIONS = [".png", ".jpg", ".jpeg"];
+export const DEFAULT_BLUR_OPTIONS = {
+    enabled: true,
+    size: 8,
+    quality: 70,
+    stdDeviation: 20,
+};
+export const DEFAULT_OPTIONS = {
+    enabled: true,
+    dirs: ["public/images", "public/icons"],
+    outDir: "public/generated",
+    maxWidth: 1920,
+    quality: 80,
+    formats: ["avif", "webp"],
+    manifest: "public/generated/images.json",
+    blur: DEFAULT_BLUR_OPTIONS,
+    dev: true,
+    cacheDir: "node_modules/.cache/cloudflare-next-intl/image-optimizer",
+    overrides: {},
+};
+export function resolveBlurOptions(blur, parentDefault = DEFAULT_BLUR_OPTIONS) {
+    if (blur === false) {
+        return { ...parentDefault, enabled: false };
+    }
+    if (blur === true) {
+        return { ...parentDefault, enabled: true };
+    }
+    if (blur === undefined) {
+        return { ...parentDefault };
+    }
+    return {
+        enabled: blur.enabled ?? parentDefault.enabled,
+        size: blur.size ?? parentDefault.size,
+        quality: blur.quality ?? parentDefault.quality,
+        stdDeviation: blur.stdDeviation ?? parentDefault.stdDeviation,
+    };
+}
+export function resolveOptions(options) {
+    const raw = options ?? {};
+    const formats = raw.formats === false ? [] : (raw.formats ?? DEFAULT_OPTIONS.formats);
+    const maxWidth = raw.maxWidth === false ? false : (raw.maxWidth ?? DEFAULT_OPTIONS.maxWidth);
+    const blur = resolveBlurOptions(raw.blur, DEFAULT_BLUR_OPTIONS);
+    return {
+        enabled: raw.enabled ?? DEFAULT_OPTIONS.enabled,
+        dirs: raw.dirs ? [...raw.dirs] : [...DEFAULT_OPTIONS.dirs],
+        outDir: raw.outDir ?? DEFAULT_OPTIONS.outDir,
+        maxWidth,
+        quality: raw.quality ?? DEFAULT_OPTIONS.quality,
+        formats: [...formats],
+        manifest: raw.manifest ?? DEFAULT_OPTIONS.manifest,
+        blur,
+        dev: raw.dev ?? DEFAULT_OPTIONS.dev,
+        cacheDir: raw.cacheDir ?? DEFAULT_OPTIONS.cacheDir,
+        overrides: raw.overrides ? { ...raw.overrides } : {},
+    };
+}
+export function resolveImageConfig(publicSrc, options) {
+    const override = options.overrides[publicSrc];
+    if (!override) {
+        return {
+            maxWidth: options.maxWidth,
+            quality: options.quality,
+            formats: options.formats,
+            blur: options.blur,
+        };
+    }
+    const formats = override.formats === false
+        ? []
+        : override.formats !== undefined
+            ? [...override.formats]
+            : options.formats;
+    const maxWidth = override.maxWidth === false
+        ? false
+        : override.maxWidth !== undefined
+            ? override.maxWidth
+            : options.maxWidth;
+    const quality = override.quality ?? options.quality;
+    const blur = override.blur !== undefined
+        ? resolveBlurOptions(override.blur, options.blur)
+        : options.blur;
+    return { maxWidth, quality, formats, blur };
+}

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

@@ -3,3 +3,4 @@ export { userAgentStubPlugin, USER_AGENT_STUB_ID, USER_AGENT_STUB_CODE } from ".
 export { cfWorkersClientStubPlugin, CF_WORKERS_CLIENT_STUB_ID, CF_WORKERS_CLIENT_STUB_CODE } from "./cf_workers_client_stub.js";
 export { localeFilePlugin, resolveDefaultIntlConfigPath, type LocaleFilePluginOptions } from "./locale_file_plugin.js";
 export { cloudflareNextIntl, cloudflareNextIntlPlugin, type CloudflareNextIntlOptions, default } from "./plugin.js";
+export { imageOptimizer, imageOptimizerPlugin, VIRTUAL_IMAGE_SHIM_ID, type ImageFormat, type ImageBlurOptions, type ImageOverrideOptions, type ImageOptimizerPluginOptions, type ResolvedBlurOptions, type ResolvedOptions, type ResolvedImageConfig, type OptimizedImage, type ManifestData, type ManifestEntry, } from "../image_optimizer/index.js";

package/dist/src/vite/index.js

@@ -3,3 +3,4 @@ export { userAgentStubPlugin, USER_AGENT_STUB_ID, USER_AGENT_STUB_CODE } from ".
 export { cfWorkersClientStubPlugin, CF_WORKERS_CLIENT_STUB_ID, CF_WORKERS_CLIENT_STUB_CODE } from "./cf_workers_client_stub.js";
 export { localeFilePlugin, resolveDefaultIntlConfigPath } from "./locale_file_plugin.js";
 export { cloudflareNextIntl, cloudflareNextIntlPlugin, default } from "./plugin.js";
+export { imageOptimizer, imageOptimizerPlugin, VIRTUAL_IMAGE_SHIM_ID, } from "../image_optimizer/index.js";

package/dist/src/vite/plugin.d.ts

@@ -1,5 +1,6 @@
 import type { Plugin } from "vite";
 import { type LocaleFilePluginOptions } from "./locale_file_plugin.js";
+import { type ImageOptimizerPluginOptions } from "../image_optimizer/index.js";
 export interface CloudflareNextIntlOptions extends LocaleFilePluginOptions {
     /**
      * Emit static `BUILD_ID` asset on client build for Vinext / Cloudflare.
@@ -23,6 +24,13 @@ export interface CloudflareNextIntlOptions extends LocaleFilePluginOptions {
      * @default true
      */
     cfWorkersClientStub?: boolean;
+    /**
+     * Build-time and dev image optimizer plugin. Automatically downscales rasters into `public/generated`,
+     * emits AVIF / WebP siblings, generates blur placeholders with SVG filters, and injects blurDataURL.
+     * Pass an options object to customize or `false` to disable.
+     * @default true
+     */
+    imageOptimizer?: boolean | ImageOptimizerPluginOptions;
 }
 export declare function cloudflareNextIntl(options?: CloudflareNextIntlOptions): Plugin[];
 export declare const cloudflareNextIntlPlugin: typeof cloudflareNextIntl;

package/dist/src/vite/plugin.js

@@ -2,8 +2,14 @@ import { buildIdAsset } from "./build_id_asset.js";
 import { userAgentStubPlugin } from "./user_agent_stub.js";
 import { cfWorkersClientStubPlugin } from "./cf_workers_client_stub.js";
 import { localeFilePlugin } from "./locale_file_plugin.js";
+import { imageOptimizerPlugin } from "../image_optimizer/index.js";
 export function cloudflareNextIntl(options = {}) {
     const plugins = [];
+    if (options.imageOptimizer !== false) {
+        plugins.push(imageOptimizerPlugin(typeof options.imageOptimizer === "object"
+            ? options.imageOptimizer
+            : undefined));
+    }
     if (options.buildIdAsset !== false) {
         const fileName = typeof options.buildIdAsset === "string" ? options.buildIdAsset : "BUILD_ID";
         plugins.push(buildIdAsset(fileName));

package/llms.txt

@@ -27,7 +27,8 @@ other subpath can be used.
 - `./db` — `withPublicDb(fn)` / `withUserDb(fn, uid?)` server-side Postgres/Drizzle context helpers (require `db` set on your `RoutingConfig`; direct Postgres or Supabase Data API with automatic PostgREST REST translation and `cfni_exec` fallback, see below).
 - `./dbEslint` — flat-config ESLint fragment banning direct `@supabase/supabase-js`, `pg`, `postgres`, and deep `dist/` imports in application code.
 - `./dbHelpers` — generic Drizzle SQL helper functions (`excluded`, `onConflictSet`, `ago`, `currentDate`, `windowCount`, `unnestLateral`, `ascNullsLast`, `alwaysTrue`, `lateral`, `aliasColumn`, `minOf`, `maxOf`, `roundReal`, `multiply`, `scalarFromCte`) for use with `./db`.
-- `./vite` — `cloudflareNextIntl(options?)` / `cloudflareNextIntlPlugin`, `buildIdAsset(fileName?)`, `localeFilePlugin(options?)`, `userAgentStubPlugin()`, `cfWorkersClientStubPlugin()`: All-in-one Vite plugin required for Vinext/Cloudflare Workers environments (bundles `@locale-file/*` via eager glob, resolves `@intl-config`, stubs Node.js `user-agent` to prevent runtime `node:fs` errors, stubs `cloudflare:workers` for client builds, and emits client `BUILD_ID`).
+- `./vite` — `cloudflareNextIntl(options?)` / `cloudflareNextIntlPlugin`, `imageOptimizerPlugin(options?)` / `imageOptimizer`, `buildIdAsset(fileName?)`, `localeFilePlugin(options?)`, `userAgentStubPlugin()`, `cfWorkersClientStubPlugin()`: All-in-one Vite plugin required for Vinext/Cloudflare Workers environments (bundles `@locale-file/*` via eager glob, resolves `@intl-config`, stubs Node.js `user-agent` to prevent runtime `node:fs` errors, stubs `cloudflare:workers` for client builds, emits client `BUILD_ID`, and runs build-time/dev Image Optimizer with Next.js blur placeholder shimming).
+- `./image-optimizer` / `./imageOptimizer` — image optimization suite: `imageOptimizerPlugin`, `imageOptimizer`, `resolveOptions`, `resolveImageConfig`, `resolveBlurOptions`, `processImage`, `makeBlurDataURL`, `getImageBlurSvg`, `renderManifest`, `writeManifest`, `isFresh`, `loadCache`, `saveCache`, `collectImages`, `run`.
 - `./errorHandling` — error reporting & stale deploy recovery barrel: `reportError`, `withErrorHandling`, `installConsoleErrorOverride`, `installGlobalErrorOverride`, `stringifyUnknown`, `formatErrorMessage`, `defaultIgnoredConsoleErrors`, `createServerErrorAction`, `isStaleDeployError`, `defaultStaleDeployPatterns`, `setStaleDeployPatterns`, `getStaleDeployPatterns`, `clearClientCache`, `useStaleDeployRecovery`, `shouldRecoverFromStaleDeploy`, `isRecentBuild`.
 - `./isStaleDeployError` — `isStaleDeployError(error, patterns?)`, `setStaleDeployPatterns(patterns)`, `getStaleDeployPatterns()`: detector returning `true` for version skew / chunk load / dynamic import / hydration errors (ChunkLoadError, failed to fetch, dynamically imported module failure, loading CSS chunk, connection closed, RSC payload failure, minified error #412, or missing stream error `undefined`) with fast pre-lowercased pattern cache and intl-config integration (`errorHandling.staleDeployPatterns`).
 - `./clearClientCache` — `clearClientCache()`: async helper wiping `window.caches`, unregistering service workers, and clearing `sessionStorage` for recovering from stale deployments.

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.8.53",
+  "version": "0.8.55",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "type": "module",
   "sideEffects": false,
   "bin": {
     "cfni-db-codegen": "bin/db_codegen.mjs",
-    "cfni-db-install-exec": "bin/db_install_exec.mjs"
+    "cfni-db-install-exec": "bin/db_install_exec.mjs",
+    "cfni-image-optimizer": "bin/image_optimizer.mjs",
+    "optimize-images": "bin/image_optimizer.mjs"
   },
   "files": [
     "dist",
@@ -221,6 +224,14 @@
     "./vite": {
       "types": "./dist/src/vite/index.d.ts",
       "import": "./dist/src/vite/index.js"
+    },
+    "./image-optimizer": {
+      "types": "./dist/src/image_optimizer/index.d.ts",
+      "import": "./dist/src/image_optimizer/index.js"
+    },
+    "./imageOptimizer": {
+      "types": "./dist/src/image_optimizer/index.d.ts",
+      "import": "./dist/src/image_optimizer/index.js"
     }
   },
   "scripts": {
@@ -271,7 +282,8 @@
     "embedded-postgres": "^18.4.0-beta.17",
     "firebase": "^12.17.0",
     "jose": "^6.2.8",
-    "pg": "^8.23.0"
+    "pg": "^8.23.0",
+    "sharp": "^0.34.5"
   },
   "peerDependencies": {
     "next": ">=12.0.0",