@inoo-ch/payload-image-optimizer 1.1.0 → 1.1.1

package/src/fields/imageOptimizerField.ts

@@ -0,0 +1,70 @@
+import type { GroupField } from 'payload'
+
+export const getImageOptimizerField = (): GroupField => ({
+  name: 'imageOptimizer',
+  type: 'group',
+  admin: {
+    position: 'sidebar',
+    readOnly: true,
+    components: {
+      Field: '@inoo-ch/payload-image-optimizer/client#OptimizationStatus',
+    },
+  },
+  fields: [
+    {
+      name: 'thumbHash',
+      type: 'text',
+    },
+    {
+      name: 'originalSize',
+      type: 'number',
+    },
+    {
+      name: 'optimizedSize',
+      type: 'number',
+    },
+    {
+      name: 'status',
+      type: 'select',
+      options: ['pending', 'processing', 'complete', 'error'],
+    },
+    {
+      name: 'error',
+      type: 'text',
+    },
+    {
+      name: 'variants',
+      type: 'array',
+      fields: [
+        {
+          name: 'format',
+          type: 'text',
+        },
+        {
+          name: 'filename',
+          type: 'text',
+        },
+        {
+          name: 'filesize',
+          type: 'number',
+        },
+        {
+          name: 'width',
+          type: 'number',
+        },
+        {
+          name: 'height',
+          type: 'number',
+        },
+        {
+          name: 'mimeType',
+          type: 'text',
+        },
+        {
+          name: 'url',
+          type: 'text',
+        },
+      ],
+    },
+  ],
+})

package/src/hooks/afterChange.ts

@@ -0,0 +1,77 @@
+import fs from 'fs/promises'
+import path from 'path'
+import type { CollectionAfterChangeHook } from 'payload'
+
+import type { ResolvedImageOptimizerConfig } from '../types.js'
+import { resolveCollectionConfig } from '../defaults.js'
+
+export const createAfterChangeHook = (
+  resolvedConfig: ResolvedImageOptimizerConfig,
+  collectionSlug: string,
+): CollectionAfterChangeHook => {
+  return async ({ context, doc, req }) => {
+    if (context?.imageOptimizer_skip) return doc
+
+    if (!req.file || !req.file.data || !req.file.mimetype?.startsWith('image/')) return doc
+
+    const collectionConfig = req.payload.collections[collectionSlug as keyof typeof req.payload.collections].config
+    let staticDir: string =
+      typeof collectionConfig.upload === 'object' ? collectionConfig.upload.staticDir || '' : ''
+
+    if (staticDir && !path.isAbsolute(staticDir)) {
+      staticDir = path.resolve(process.cwd(), staticDir)
+    }
+
+    const perCollectionConfig = resolveCollectionConfig(resolvedConfig, collectionSlug)
+
+    // Overwrite the file on disk with the processed (stripped/resized/converted) buffer
+    // Payload 3.0 writes the original buffer to disk; we replace it here
+    const processedBuffer = context.imageOptimizer_processedBuffer as Buffer | undefined
+    if (processedBuffer && doc.filename && staticDir) {
+      const safeFilename = path.basename(doc.filename as string)
+      const filePath = path.join(staticDir, safeFilename)
+      await fs.writeFile(filePath, processedBuffer)
+
+      // If replaceOriginal changed the filename, clean up the old file Payload wrote
+      const originalFilename = context.imageOptimizer_originalFilename as string | undefined
+      if (originalFilename && originalFilename !== safeFilename) {
+        const oldFilePath = path.join(staticDir, path.basename(originalFilename))
+        await fs.unlink(oldFilePath).catch(() => {
+          // Old file may not exist if Payload used the new filename
+        })
+      }
+    }
+
+    // When replaceOriginal is on and only one format is configured, the main file
+    // is already converted — skip the async job and mark complete immediately.
+    if (perCollectionConfig.replaceOriginal && perCollectionConfig.formats.length <= 1) {
+      await req.payload.update({
+        collection: collectionSlug,
+        id: doc.id,
+        data: {
+          imageOptimizer: {
+            status: 'complete',
+            variants: [],
+          },
+        },
+        context: { imageOptimizer_skip: true },
+      })
+      return doc
+    }
+
+    // Queue async format conversion job for remaining variants
+    await req.payload.jobs.queue({
+      task: 'imageOptimizer_convertFormats',
+      input: {
+        collectionSlug,
+        docId: String(doc.id),
+      },
+    })
+
+    req.payload.jobs.run().catch((err: unknown) => {
+      req.payload.logger.error({ err }, 'Image optimizer job runner failed')
+    })
+
+    return doc
+  }
+}

package/src/hooks/beforeChange.ts

@@ -0,0 +1,64 @@
+import path from 'path'
+import type { CollectionBeforeChangeHook } from 'payload'
+
+import type { ResolvedImageOptimizerConfig } from '../types.js'
+import { resolveCollectionConfig } from '../defaults.js'
+import { convertFormat, generateThumbHash, stripAndResize } from '../processing/index.js'
+
+export const createBeforeChangeHook = (
+  resolvedConfig: ResolvedImageOptimizerConfig,
+  collectionSlug: string,
+): CollectionBeforeChangeHook => {
+  return async ({ context, data, req }) => {
+    if (context?.imageOptimizer_skip) return data
+
+    if (!req.file || !req.file.data || !req.file.mimetype?.startsWith('image/')) return data
+
+    const originalSize = req.file.data.length
+
+    const perCollectionConfig = resolveCollectionConfig(resolvedConfig, collectionSlug)
+
+    // Process in memory: strip EXIF, resize, generate blur
+    const processed = await stripAndResize(
+      req.file.data,
+      perCollectionConfig.maxDimensions,
+      resolvedConfig.stripMetadata,
+    )
+
+    let finalBuffer = processed.buffer
+    let finalSize = processed.size
+
+    if (perCollectionConfig.replaceOriginal && perCollectionConfig.formats.length > 0) {
+      // Convert to primary format (first in the formats array)
+      const primaryFormat = perCollectionConfig.formats[0]
+      const converted = await convertFormat(processed.buffer, primaryFormat.format, primaryFormat.quality)
+
+      finalBuffer = converted.buffer
+      finalSize = converted.size
+
+      // Update filename and mimeType so Payload stores the correct metadata
+      const originalFilename = data.filename || req.file.name || ''
+      const newFilename = `${path.parse(originalFilename).name}.${primaryFormat.format}`
+      context.imageOptimizer_originalFilename = originalFilename
+      data.filename = newFilename
+      data.mimeType = converted.mimeType
+      data.filesize = finalSize
+    }
+
+    data.imageOptimizer = {
+      originalSize,
+      optimizedSize: finalSize,
+      status: 'pending',
+    }
+
+    if (resolvedConfig.generateThumbHash) {
+      data.imageOptimizer.thumbHash = await generateThumbHash(finalBuffer)
+    }
+
+    // Store processed buffer in context for afterChange to write to disk
+    // (Payload 3.0 does not use modified req.file.data for the disk write)
+    context.imageOptimizer_processedBuffer = finalBuffer
+
+    return data
+  }
+}

package/src/index.ts

@@ -0,0 +1,125 @@
+import type { Config } from 'payload'
+
+import type { ImageOptimizerConfig } from './types.js'
+import { resolveConfig } from './defaults.js'
+import { getImageOptimizerField } from './fields/imageOptimizerField.js'
+import { createBeforeChangeHook } from './hooks/beforeChange.js'
+import { createAfterChangeHook } from './hooks/afterChange.js'
+import { createConvertFormatsHandler } from './tasks/convertFormats.js'
+import { createRegenerateDocumentHandler } from './tasks/regenerateDocument.js'
+import { createRegenerateHandler, createRegenerateStatusHandler } from './endpoints/regenerate.js'
+
+export type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig } from './types.js'
+
+export { encodeImageToThumbHash, decodeThumbHashToDataURL } from './utilities/thumbhash.js'
+
+export const imageOptimizer =
+  (pluginOptions: ImageOptimizerConfig) =>
+  (config: Config): Config => {
+    const resolvedConfig = resolveConfig(pluginOptions)
+
+    if (!config.collections) {
+      config.collections = []
+    }
+
+    // Inject imageOptimizer fields into targeted upload collections
+    for (const collectionSlug in resolvedConfig.collections) {
+      const collection = config.collections.find((c) => c.slug === collectionSlug)
+
+      if (collection) {
+        collection.fields.push(getImageOptimizerField())
+      }
+    }
+
+    // If disabled, keep fields for schema consistency but skip hooks/tasks
+    if (resolvedConfig.disabled) {
+      return config
+    }
+
+    // Inject hooks into targeted upload collections
+    for (const collectionSlug in resolvedConfig.collections) {
+      const collection = config.collections.find((c) => c.slug === collectionSlug)
+
+      if (collection) {
+        if (!collection.hooks) {
+          collection.hooks = {}
+        }
+
+        if (!collection.hooks.beforeChange) {
+          collection.hooks.beforeChange = []
+        }
+        collection.hooks.beforeChange.push(createBeforeChangeHook(resolvedConfig, collectionSlug))
+
+        if (!collection.hooks.afterChange) {
+          collection.hooks.afterChange = []
+        }
+        collection.hooks.afterChange.push(createAfterChangeHook(resolvedConfig, collectionSlug))
+
+        // Add RegenerationButton to the collection list view
+        if (!collection.admin) {
+          collection.admin = {}
+        }
+        if (!collection.admin.components) {
+          collection.admin.components = {}
+        }
+        if (!collection.admin.components.beforeListTable) {
+          collection.admin.components.beforeListTable = []
+        }
+        collection.admin.components.beforeListTable.push(
+          '@inoo-ch/payload-image-optimizer/client#RegenerationButton',
+        )
+      }
+    }
+
+    // Register async format conversion job task
+    if (!config.jobs) {
+      config.jobs = { tasks: [] }
+    }
+    if (!config.jobs!.tasks) {
+      config.jobs!.tasks = []
+    }
+
+    config.jobs!.tasks!.push({
+      slug: 'imageOptimizer_convertFormats',
+      inputSchema: [
+        { name: 'collectionSlug', type: 'text', required: true },
+        { name: 'docId', type: 'text', required: true },
+      ],
+      outputSchema: [
+        { name: 'variantsGenerated', type: 'number' },
+      ],
+      retries: 2,
+      handler: createConvertFormatsHandler(resolvedConfig),
+    } as any)
+
+    config.jobs!.tasks!.push({
+      slug: 'imageOptimizer_regenerateDocument',
+      inputSchema: [
+        { name: 'collectionSlug', type: 'text', required: true },
+        { name: 'docId', type: 'text', required: true },
+      ],
+      outputSchema: [
+        { name: 'status', type: 'text' },
+        { name: 'reason', type: 'text' },
+      ],
+      retries: 2,
+      handler: createRegenerateDocumentHandler(resolvedConfig),
+    } as any)
+
+    // Register regeneration endpoints
+    if (!config.endpoints) config.endpoints = []
+
+    config.endpoints.push({
+      path: '/image-optimizer/regenerate',
+      method: 'post',
+      handler: createRegenerateHandler(resolvedConfig),
+    })
+
+    config.endpoints.push({
+      path: '/image-optimizer/regenerate',
+      method: 'get',
+      handler: createRegenerateStatusHandler(resolvedConfig),
+    })
+
+    return config
+  }

package/src/next-image.d.ts

@@ -0,0 +1,3 @@
+declare module 'next/image' {
+  export { default, ImageProps } from 'next/dist/shared/lib/image-external'
+}

package/src/processing/index.ts

@@ -0,0 +1,59 @@
+import sharp from 'sharp'
+import { rgbaToThumbHash } from 'thumbhash'
+
+export async function stripAndResize(
+  buffer: Buffer,
+  maxDimensions: { width: number; height: number },
+  stripMetadata: boolean,
+): Promise<{ buffer: Buffer; width: number; height: number; size: number }> {
+  let pipeline = sharp(buffer)
+    .rotate()
+    .resize(maxDimensions.width, maxDimensions.height, {
+      fit: 'inside',
+      withoutEnlargement: true,
+    })
+
+  if (!stripMetadata) {
+    pipeline = pipeline.keepMetadata()
+  }
+
+  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true })
+
+  return {
+    buffer: data,
+    width: info.width,
+    height: info.height,
+    size: info.size,
+  }
+}
+
+export async function generateThumbHash(buffer: Buffer): Promise<string> {
+  const { data, info } = await sharp(buffer)
+    .resize(100, 100, { fit: 'inside' })
+    .raw()
+    .ensureAlpha()
+    .toBuffer({ resolveWithObject: true })
+
+  const thumbHash = rgbaToThumbHash(info.width, info.height, data)
+  return Buffer.from(thumbHash).toString('base64')
+}
+
+export async function convertFormat(
+  buffer: Buffer,
+  format: 'webp' | 'avif',
+  quality: number,
+): Promise<{ buffer: Buffer; width: number; height: number; size: number; mimeType: string }> {
+  const { data, info } = await sharp(buffer)
+    .toFormat(format, { quality })
+    .toBuffer({ resolveWithObject: true })
+
+  const mimeType = format === 'webp' ? 'image/webp' : 'image/avif'
+
+  return {
+    buffer: data,
+    width: info.width,
+    height: info.height,
+    size: info.size,
+    mimeType,
+  }
+}

package/src/tasks/convertFormats.ts

@@ -0,0 +1,107 @@
+import fs from 'fs/promises'
+import path from 'path'
+
+import type { CollectionSlug } from 'payload'
+
+import type { ResolvedImageOptimizerConfig } from '../types.js'
+import { resolveCollectionConfig } from '../defaults.js'
+import { convertFormat } from '../processing/index.js'
+
+export const createConvertFormatsHandler = (resolvedConfig: ResolvedImageOptimizerConfig) => {
+  return async ({ input, req }: { input: { collectionSlug: string; docId: string }; req: any }) => {
+    try {
+      const doc = await req.payload.findByID({
+        collection: input.collectionSlug as CollectionSlug,
+        id: input.docId,
+      })
+
+      const collectionConfig = req.payload.collections[input.collectionSlug as keyof typeof req.payload.collections].config
+
+      let staticDir: string =
+        typeof collectionConfig.upload === 'object' ? collectionConfig.upload.staticDir || '' : ''
+      if (!staticDir) {
+        throw new Error(`No staticDir configured for collection "${input.collectionSlug}"`)
+      }
+      if (!path.isAbsolute(staticDir)) {
+        staticDir = path.resolve(process.cwd(), staticDir)
+      }
+
+      // Sanitize filename to prevent path traversal
+      const safeFilename = path.basename(doc.filename)
+      const filePath = path.join(staticDir, safeFilename)
+      const fileBuffer = await fs.readFile(filePath)
+
+      const variants: Array<{
+        filename: string
+        filesize: number
+        format: string
+        height: number
+        mimeType: string
+        url: string
+        width: number
+      }> = []
+
+      const perCollectionConfig = resolveCollectionConfig(resolvedConfig, input.collectionSlug)
+
+      // When replaceOriginal is on, the main file is already in the primary format —
+      // skip it and only generate variants for the remaining formats.
+      const formatsToGenerate = perCollectionConfig.replaceOriginal && perCollectionConfig.formats.length > 0
+        ? perCollectionConfig.formats.slice(1)
+        : perCollectionConfig.formats
+
+      for (const format of formatsToGenerate) {
+        const result = await convertFormat(fileBuffer, format.format, format.quality)
+        const variantFilename = `${path.parse(safeFilename).name}-optimized.${format.format}`
+
+        await fs.writeFile(path.join(staticDir, variantFilename), result.buffer)
+
+        variants.push({
+          format: format.format,
+          filename: variantFilename,
+          filesize: result.size,
+          width: result.width,
+          height: result.height,
+          mimeType: result.mimeType,
+          url: `/api/${input.collectionSlug}/file/${variantFilename}`,
+        })
+      }
+
+      await req.payload.update({
+        collection: input.collectionSlug as CollectionSlug,
+        id: input.docId,
+        data: {
+          imageOptimizer: {
+            status: 'complete',
+            variants,
+          },
+        },
+        context: { imageOptimizer_skip: true },
+      })
+
+      return { output: { variantsGenerated: variants.length } }
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err)
+
+      try {
+        await req.payload.update({
+          collection: input.collectionSlug as CollectionSlug,
+          id: input.docId,
+          data: {
+            imageOptimizer: {
+              status: 'error',
+              error: errorMessage,
+            },
+          },
+          context: { imageOptimizer_skip: true },
+        })
+      } catch (updateErr) {
+        req.payload.logger.error(
+          { err: updateErr },
+          'Failed to persist error status for image optimizer',
+        )
+      }
+
+      throw err
+    }
+  }
+}

package/src/tasks/regenerateDocument.ts

@@ -0,0 +1,177 @@
+import fs from 'fs/promises'
+import path from 'path'
+
+import type { CollectionSlug } from 'payload'
+
+import type { ResolvedImageOptimizerConfig } from '../types.js'
+import { resolveCollectionConfig } from '../defaults.js'
+import { stripAndResize, generateThumbHash, convertFormat } from '../processing/index.js'
+
+export const createRegenerateDocumentHandler = (resolvedConfig: ResolvedImageOptimizerConfig) => {
+  return async ({ input, req }: { input: { collectionSlug: string; docId: string }; req: any }) => {
+    try {
+      const doc = await req.payload.findByID({
+        collection: input.collectionSlug as CollectionSlug,
+        id: input.docId,
+      })
+
+      // Skip non-image documents
+      if (!doc.mimeType || !doc.mimeType.startsWith('image/')) {
+        return { output: { status: 'skipped', reason: 'not-image' } }
+      }
+
+      const collectionConfig = req.payload.collections[input.collectionSlug as keyof typeof req.payload.collections].config
+
+      let staticDir: string =
+        typeof collectionConfig.upload === 'object' ? collectionConfig.upload.staticDir || '' : ''
+      if (!staticDir) {
+        throw new Error(`No staticDir configured for collection "${input.collectionSlug}"`)
+      }
+      if (!path.isAbsolute(staticDir)) {
+        staticDir = path.resolve(process.cwd(), staticDir)
+      }
+
+      // Sanitize filename to prevent path traversal
+      const safeFilename = path.basename(doc.filename)
+      const filePath = path.join(staticDir, safeFilename)
+
+      let fileBuffer: Buffer
+      try {
+        fileBuffer = await fs.readFile(filePath)
+      } catch {
+        // If file not on disk, try fetching from URL
+        if (doc.url) {
+          const url = doc.url.startsWith('http')
+            ? doc.url
+            : `${process.env.NEXT_PUBLIC_SERVER_URL || ''}${doc.url}`
+          const response = await fetch(url)
+          fileBuffer = Buffer.from(await response.arrayBuffer())
+        } else {
+          throw new Error(`File not found: ${filePath}`)
+        }
+      }
+
+      const originalSize = fileBuffer.length
+      const perCollectionConfig = resolveCollectionConfig(resolvedConfig, input.collectionSlug)
+
+      // Step 1: Strip metadata + resize
+      const processed = await stripAndResize(
+        fileBuffer,
+        perCollectionConfig.maxDimensions,
+        resolvedConfig.stripMetadata,
+      )
+
+      let mainBuffer = processed.buffer
+      let mainSize = processed.size
+      let newFilename = safeFilename
+      let newMimeType: string | undefined
+
+      // Step 1b: If replaceOriginal, convert main file to primary format
+      if (perCollectionConfig.replaceOriginal && perCollectionConfig.formats.length > 0) {
+        const primaryFormat = perCollectionConfig.formats[0]
+        const converted = await convertFormat(processed.buffer, primaryFormat.format, primaryFormat.quality)
+        mainBuffer = converted.buffer
+        mainSize = converted.size
+        newFilename = `${path.parse(safeFilename).name}.${primaryFormat.format}`
+        newMimeType = converted.mimeType
+      }
+
+      // Write optimized file to disk
+      const newFilePath = path.join(staticDir, newFilename)
+      await fs.writeFile(newFilePath, mainBuffer)
+
+      // Clean up old file if filename changed
+      if (newFilename !== safeFilename) {
+        await fs.unlink(filePath).catch(() => {})
+      }
+
+      // Step 2: Generate ThumbHash
+      let thumbHash: string | undefined
+      if (resolvedConfig.generateThumbHash) {
+        thumbHash = await generateThumbHash(mainBuffer)
+      }
+
+      // Step 3: Convert to configured formats (skip primary when replaceOriginal)
+      const formatsToGenerate = perCollectionConfig.replaceOriginal && perCollectionConfig.formats.length > 0
+        ? perCollectionConfig.formats.slice(1)
+        : perCollectionConfig.formats
+
+      const variants: Array<{
+        filename: string
+        filesize: number
+        format: string
+        height: number
+        mimeType: string
+        url: string
+        width: number
+      }> = []
+
+      for (const format of formatsToGenerate) {
+        const result = await convertFormat(mainBuffer, format.format, format.quality)
+        const variantFilename = `${path.parse(newFilename).name}-optimized.${format.format}`
+        await fs.writeFile(path.join(staticDir, variantFilename), result.buffer)
+
+        variants.push({
+          format: format.format,
+          filename: variantFilename,
+          filesize: result.size,
+          width: result.width,
+          height: result.height,
+          mimeType: result.mimeType,
+          url: `/api/${input.collectionSlug}/file/${variantFilename}`,
+        })
+      }
+
+      // Step 4: Update the document with all optimization data
+      const updateData: Record<string, any> = {
+        imageOptimizer: {
+          originalSize,
+          optimizedSize: mainSize,
+          status: 'complete',
+          thumbHash,
+          variants,
+          error: null,
+        },
+      }
+
+      // Update filename, mimeType, and filesize when replaceOriginal changed them
+      if (newFilename !== safeFilename) {
+        updateData.filename = newFilename
+        updateData.filesize = mainSize
+        updateData.mimeType = newMimeType
+      }
+
+      await req.payload.update({
+        collection: input.collectionSlug as CollectionSlug,
+        id: input.docId,
+        data: updateData,
+        context: { imageOptimizer_skip: true },
+      })
+
+      return { output: { status: 'complete' } }
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err)
+
+      try {
+        await req.payload.update({
+          collection: input.collectionSlug as CollectionSlug,
+          id: input.docId,
+          data: {
+            imageOptimizer: {
+              status: 'error',
+              error: errorMessage,
+            },
+          },
+          context: { imageOptimizer_skip: true },
+        })
+      } catch (updateErr) {
+        req.payload.logger.error(
+          { err: updateErr },
+          'Failed to persist error status for image optimizer regeneration',
+        )
+      }
+
+      throw err
+    }
+  }
+}