ImageKit Storage for Payload (beta)

This package integrates ImageKit with Payload using the official @payloadcms/plugin-cloud-storage.

• Uploads go directly to ImageKit.
• Documents store filename, url, and optional transformations.
• Optional named transformations are exposed on the document as read‑only text fields.

Changelog

• Addeed support for Named Transformations
• Changed type for DefaultTrasnformation and Transformations

Installation

pnpm add @lussoadv/payloadcms-storage-imagekit

Basic usage

Register the plugin in your payload.config.ts:

import { imagekitPlugin } from '@lussoadv/payloadcms-storage-imagekit'

export default buildConfig({
  // ...
  plugins: [
    imagekitPlugin({
      publicKey: process.env.IMAGE_KIT_PUBLIC_KEY!,
      privateKey: process.env.IMAGE_KIT_PRIVATE_KEY!,
      urlEndpoint: process.env.IMAGE_KIT_URL_ENDPOINT!,
      options: {
        restrictSignedUrl: true | false, // In ImageKit security options enabled, the plugin generate signed urls
      },
      collections: {
        media: {
          // Base folder in ImageKit. If omitted, the collection slug is used.
          folder: 'media',

          // Optional prefix inside the folder, useful for sub‑grouping.
          // prefix: 'uploads',

          // Disable Payload's local storage for this collection.
          disableLocalStorage: true,

          // Additional ImageKit options applied on upload / URL generation.
          options: {
            useUniqueFileName: false,
            tags: ['tag-1', 'tag-2'],

            /**
             * Default expiry (in seconds) for signed URLs generated
             * by generateURL, static handler and transformation URLs.
             */
            expireSeconds: 3600,
          },

          /**
           * Optional named transformations.
           * For each entry, a read‑only text field with the same `name`
           * will be added to the collection and populated afterRead
           * with a signed URL for that transformation.
           */
          defaultTransformation: 
            // Applied on generateUrl handler in the api response url => defaultTransformation
            { named: true, transformation: "named_transformation"} or 
            { width: '600', aspectRatio: '3-4', focus: 'auto', crop: 'at_max' }, //Transformation Type

          transformations: [
            { 
              name: 'thumbnail',
              named: true, 
              transformation: "named_transformation"
            } or 
            {
              name: 'thumbnail',
              transformation: { width: '300', height: '300', crop: 'at_max' } //Transformation Type
            },
          ],
        },
      },
    }),
  ],
})

How paths are built

For a given collection:

• Upload folder in ImageKit:

  • folder || collection.slug is used as base folder.
  • If prefix is set, files are uploaded under <baseFolder>/<prefix>.

• The same base folder/prefix convention is used by:

  • handleUpload when sending files to ImageKit.
  • generateURL when building signed or unsigned URLs.
  • staticHandler when redirecting to signed or unsigned URLs.
  • handleDelete when falling back to listFiles if fileId is not stored.

This keeps upload, URL generation, static proxying and deletion in sync.