@inoo-ch/payload-image-optimizer 1.3.3 → 1.3.5

package/README.md

@@ -128,6 +128,32 @@ collections: {
 
 All format conversion runs as async background jobs, so uploads return immediately.
 
+## How It Differs from Payload's Default Image Handling
+
+Payload CMS ships with [sharp](https://sharp.pixelplumbing.com/) built-in and can resize images and generate sizes on upload. This plugin **does not double-process your images** — it intercepts the raw upload in a `beforeChange` hook *before* Payload's own sharp pipeline runs, and writes the optimized buffer back to `req.file.data`. When Payload's built-in `uploadFiles` step kicks in to generate your configured sizes, it works from the already-optimized file, not the raw original.
+
+### Comparison
+
+| Capability | Payload Default | With This Plugin |
+|---|---|---|
+| Resize to max dimensions | Manual via `imageSizes` config | Automatic — configure once globally or per-collection |
+| WebP/AVIF conversion | Requires custom hooks | Built-in, zero-config |
+| EXIF metadata stripping | Not built-in | Automatic (configurable) |
+| Blur hash placeholders | Requires custom hooks | ThumbHash generated automatically |
+| Optimization status & savings | Not available | Admin sidebar panel per image |
+| Bulk re-process existing images | Not available | One-click regeneration with progress tracking |
+| Next.js `<Image>` with blur placeholder | Manual wiring | Drop-in `<ImageBox>` component |
+| Per-collection format/quality overrides | N/A | Supported |
+
+### CPU & Resource Impact
+
+- **Single-format mode** (e.g. WebP only with `replaceOriginal: true`) adds virtually zero overhead compared to Payload's default sharp processing — the plugin replaces the sharp pass rather than adding a second one.
+- **Additional format variants** (e.g. both WebP and AVIF) run as background jobs after upload — this is the one area where you'll see extra CPU usage vs vanilla Payload.
+- **ThumbHash generation** processes a 100×100px thumbnail — negligible impact.
+- **Bulk regeneration** processes images sequentially, not all at once, so it won't spike your server.
+
+If you're on a resource-constrained server, use single-format mode and you'll be at roughly the same CPU cost as stock Payload.
+
 ## Admin UI
 
 The plugin adds an **Optimization Status** panel to the document sidebar showing:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inoo-ch/payload-image-optimizer",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Payload CMS plugin for automatic image optimization — WebP/AVIF conversion, resize, EXIF strip, ThumbHash placeholders, and bulk regeneration",
   "license": "MIT",
   "keywords": [

package/dist/components/ImageBox.d.ts

@@ -1,8 +0,0 @@
-import React from 'react';
-import { type ImageProps } from 'next/image';
-import type { MediaResource } from '../types.js';
-export interface ImageBoxProps extends Omit<ImageProps, 'src' | 'alt'> {
-    media: MediaResource | string;
-    alt?: string;
-}
-export declare const ImageBox: React.FC<ImageBoxProps>;

package/dist/components/OptimizationStatus.d.ts

@@ -1,4 +0,0 @@
-import React from 'react';
-export declare const OptimizationStatus: React.FC<{
-    path?: string;
-}>;

package/dist/components/RegenerationButton.d.ts

@@ -1,2 +0,0 @@
-import React from 'react';
-export declare const RegenerationButton: React.FC;

package/dist/defaults.d.ts

@@ -1,3 +0,0 @@
-import type { ImageOptimizerConfig, ResolvedCollectionOptimizerConfig, ResolvedImageOptimizerConfig } from './types.js';
-export declare const resolveConfig: (config: ImageOptimizerConfig) => ResolvedImageOptimizerConfig;
-export declare const resolveCollectionConfig: (resolvedConfig: ResolvedImageOptimizerConfig, collectionSlug: string) => ResolvedCollectionOptimizerConfig;

package/dist/endpoints/regenerate.d.ts

@@ -1,4 +0,0 @@
-import type { PayloadHandler } from 'payload';
-import type { ResolvedImageOptimizerConfig } from '../types.js';
-export declare const createRegenerateHandler: (resolvedConfig: ResolvedImageOptimizerConfig) => PayloadHandler;
-export declare const createRegenerateStatusHandler: (resolvedConfig: ResolvedImageOptimizerConfig) => PayloadHandler;

package/dist/exports/client.d.ts

@@ -1,6 +0,0 @@
-export { OptimizationStatus } from '../components/OptimizationStatus.js';
-export { ImageBox } from '../components/ImageBox.js';
-export type { ImageBoxProps } from '../components/ImageBox.js';
-export { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
-export type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
-export { RegenerationButton } from '../components/RegenerationButton.js';

package/dist/exports/rsc.d.ts

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

package/dist/fields/imageOptimizerField.d.ts

@@ -1,4 +0,0 @@
-import type { Field, GroupField } from 'payload';
-import type { FieldsOverride } from '../types.js';
-export declare const defaultImageOptimizerFields: Field[];
-export declare const getImageOptimizerField: (fieldsOverride?: FieldsOverride) => GroupField;

package/dist/hooks/afterChange.d.ts

@@ -1,3 +0,0 @@
-import type { CollectionAfterChangeHook } from 'payload';
-import type { ResolvedImageOptimizerConfig } from '../types.js';
-export declare const createAfterChangeHook: (resolvedConfig: ResolvedImageOptimizerConfig, collectionSlug: string) => CollectionAfterChangeHook;

package/dist/hooks/beforeChange.d.ts

@@ -1,3 +0,0 @@
-import type { CollectionBeforeChangeHook } from 'payload';
-import type { ResolvedImageOptimizerConfig } from '../types.js';
-export declare const createBeforeChangeHook: (resolvedConfig: ResolvedImageOptimizerConfig, collectionSlug: string) => CollectionBeforeChangeHook;

package/dist/index.d.ts

@@ -1,6 +0,0 @@
-import type { Config } from 'payload';
-import type { ImageOptimizerConfig } from './types.js';
-export type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig, ImageOptimizerData, MediaResource, FieldsOverride } from './types.js';
-export { defaultImageOptimizerFields } from './fields/imageOptimizerField.js';
-export { encodeImageToThumbHash, decodeThumbHashToDataURL } from './utilities/thumbhash.js';
-export declare const imageOptimizer: (pluginOptions: ImageOptimizerConfig) => (config: Config) => Config;

package/dist/processing/index.d.ts

@@ -1,17 +0,0 @@
-export declare function stripAndResize(buffer: Buffer, maxDimensions: {
-    width: number;
-    height: number;
-}, stripMetadata: boolean): Promise<{
-    buffer: Buffer;
-    width: number;
-    height: number;
-    size: number;
-}>;
-export declare function generateThumbHash(buffer: Buffer): Promise<string>;
-export declare function convertFormat(buffer: Buffer, format: 'webp' | 'avif', quality: number): Promise<{
-    buffer: Buffer;
-    width: number;
-    height: number;
-    size: number;
-    mimeType: string;
-}>;

package/dist/tasks/convertFormats.d.ts

@@ -1,12 +0,0 @@
-import type { ResolvedImageOptimizerConfig } from '../types.js';
-export declare const createConvertFormatsHandler: (resolvedConfig: ResolvedImageOptimizerConfig) => ({ input, req }: {
-    input: {
-        collectionSlug: string;
-        docId: string;
-    };
-    req: any;
-}) => Promise<{
-    output: {
-        variantsGenerated: number;
-    };
-}>;

package/dist/tasks/regenerateDocument.d.ts

@@ -1,18 +0,0 @@
-import type { ResolvedImageOptimizerConfig } from '../types.js';
-export declare const createRegenerateDocumentHandler: (resolvedConfig: ResolvedImageOptimizerConfig) => ({ input, req }: {
-    input: {
-        collectionSlug: string;
-        docId: string;
-    };
-    req: any;
-}) => Promise<{
-    output: {
-        status: string;
-        reason: string;
-    };
-} | {
-    output: {
-        status: string;
-        reason?: undefined;
-    };
-}>;

package/dist/translations/index.d.ts

@@ -1 +0,0 @@
-export declare const translations: Record<string, Record<string, Record<string, string>>>;

package/dist/types.d.ts

@@ -1,57 +0,0 @@
-import type { CollectionSlug, Field } from 'payload';
-export type ImageFormat = 'webp' | 'avif';
-export type FormatQuality = {
-    format: ImageFormat;
-    quality: number;
-};
-export type CollectionOptimizerConfig = {
-    formats?: FormatQuality[];
-    maxDimensions?: {
-        width: number;
-        height: number;
-    };
-    replaceOriginal?: boolean;
-};
-export type FieldsOverride = (args: {
-    defaultFields: Field[];
-}) => Field[];
-export type ImageOptimizerConfig = {
-    collections: Partial<Record<CollectionSlug, true | CollectionOptimizerConfig>>;
-    disabled?: boolean;
-    fieldsOverride?: FieldsOverride;
-    formats?: FormatQuality[];
-    generateThumbHash?: boolean;
-    maxDimensions?: {
-        width: number;
-        height: number;
-    };
-    replaceOriginal?: boolean;
-    stripMetadata?: boolean;
-};
-export type ResolvedCollectionOptimizerConfig = {
-    formats: FormatQuality[];
-    maxDimensions: {
-        width: number;
-        height: number;
-    };
-    replaceOriginal: boolean;
-};
-export type ResolvedImageOptimizerConfig = Required<Pick<ImageOptimizerConfig, 'formats' | 'generateThumbHash' | 'maxDimensions' | 'stripMetadata'>> & {
-    collections: ImageOptimizerConfig['collections'];
-    disabled: boolean;
-    replaceOriginal: boolean;
-};
-export type ImageOptimizerData = {
-    thumbHash?: string | null;
-};
-export type MediaResource = {
-    url?: string | null;
-    alt?: string | null;
-    width?: number | null;
-    height?: number | null;
-    filename?: string | null;
-    focalX?: number | null;
-    focalY?: number | null;
-    imageOptimizer?: ImageOptimizerData | null;
-    updatedAt?: string;
-};

package/dist/utilities/getImageOptimizerProps.d.ts

@@ -1,24 +0,0 @@
-import type { MediaResource } from '../types.js';
-export type ImageOptimizerProps = {
-    placeholder: 'blur' | 'empty';
-    blurDataURL?: string;
-    style: {
-        objectPosition: string;
-    };
-};
-/**
- * Extracts image optimization props from a Payload media resource.
- *
- * Returns props that can be spread onto a Next.js `<Image>` component to add
- * ThumbHash blur placeholders and focal-point-based object positioning.
- *
- * Works with any component — including the Payload website template's `ImageMedia`:
- *
- * ```tsx
- * import { getImageOptimizerProps } from '@inoo-ch/payload-image-optimizer/client'
- *
- * const optimizerProps = getImageOptimizerProps(resource)
- * <NextImage {...existingProps} {...optimizerProps} />
- * ```
- */
-export declare function getImageOptimizerProps(resource: MediaResource | null | undefined): ImageOptimizerProps;

package/dist/utilities/resolveStaticDir.d.ts

@@ -1,3 +0,0 @@
-export declare function resolveStaticDir(collectionConfig: {
-    upload?: boolean | Record<string, any>;
-}): string;

package/dist/utilities/storage.d.ts

@@ -1,18 +0,0 @@
-/**
- * Returns true when the collection uses cloud/external storage (disableLocalStorage: true).
- * When true, files are uploaded by external adapter hooks — no local FS writes should happen.
- */
-export declare function isCloudStorage(collectionConfig: {
-    upload?: boolean | Record<string, any>;
-}): boolean;
-/**
- * Reads a file buffer from local disk or fetches it from URL.
- * Tries local disk first (when available), falls back to URL fetch.
- * This makes the plugin storage-agnostic — works with local FS and cloud storage alike.
- */
-export declare function fetchFileBuffer(doc: {
-    filename?: string;
-    url?: string;
-}, collectionConfig: {
-    upload?: boolean | Record<string, any>;
-}): Promise<Buffer>;

package/dist/utilities/thumbhash.d.ts

@@ -1,2 +0,0 @@
-export declare function encodeImageToThumbHash(buffer: Buffer, width: number, height: number): string;
-export declare function decodeThumbHashToDataURL(thumbHash: string): string;