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

``sh
pnpm add @lussoadv/payloadcms-storage-imagekit
`

Basic usage

Register the plugin in your payload.config.ts:

`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 /.

- 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.