npm package: @lussoadv/payloadcms-storage-imagekit
Description: ImageKit storage adapter for Payload using @payload/plugin-cloud-storage
Latest version: 1.0.9

# ImageKit Storage for Payload (beta)

This package integrates [ImageKit](https://imagekit.io) 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 `<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.