payload-storage-imagekit

ImageKit storage adapter plugin for Payload CMS uploads.

This plugin integrates @payloadcms/plugin-cloud-storage with ImageKit and provides:

• Uploads to ImageKit per collection
• Optional client-side uploads for Payload admin to bypass request size limits on platforms like Vercel
• Required root folder with per-collection subfolders
• Stored ImageKit references (imagekit.fileId, imagekit.url, imagekit.thumbnailUrl)
• crop: false for configured upload collections
• Admin thumbnails using ImageKit transforms (tr=w-300,h-300)
• Built-in thumbnail path for videos and PDFs in admin previews
• Migration utility for copying collection files between ImageKit folders

Installation

pnpm add @humaan/payload-storage-imagekit

Usage

import { buildConfig } from 'payload'
import { imagekitStorage } from '@humaan/payload-storage-imagekit'

export default buildConfig({
  collections: [
    {
      slug: 'media',
      upload: true,
      fields: [],
    },
  ],
  plugins: [
    imagekitStorage({
      clientUploads: true,
      folder: '/payload-uploads',
      collections: {
        media: true,
      },
      privateKey: process.env.IMAGEKIT_PRIVATE_KEY || '',
      publicKey: process.env.IMAGEKIT_PUBLIC_KEY || '',
      urlEndpoint: process.env.IMAGEKIT_URL_ENDPOINT || '',
    }),
  ],
})

Configuration

imagekitStorage(options) options:

• collections (required): Partial<Record<UploadCollectionSlug, true>>
• folder (required): root upload folder in ImageKit, e.g. /payload-uploads
• privateKey (required): ImageKit private API key
• publicKey (required): ImageKit public key
• urlEndpoint (required): ImageKit URL endpoint, e.g. https://ik.imagekit.io/your_id
• clientUploads (optional): when true, Payload admin uploads go directly from the browser to ImageKit before Payload fetches the file back for persistence and image-size generation. This helps avoid server request body limits such as Vercel's. Duplicate filenames still follow Payload's normal safe-name behavior, so a second pug.jpg becomes pug-1.jpg instead of overwriting the first asset in ImageKit.
• enabled (optional): enable / disable plugin
• alwaysInsertFields (optional): pass-through to cloud storage plugin
• disablePayloadAccessControl (optional): pass-through to cloud storage plugin

Exports

• imagekitStorage (primary)
• migrateFolder
• payloadStorageImagekit (alias of imagekitStorage)

Folder Migration

Use migrateFolder to copy uploads from one ImageKit root folder to another (e.g. staging to production).

Behavior:

• Copies files one-by-one per collection
• Creates destination folders automatically if they do not exist
• Optional database update via Payload local API
• Dry-run is enabled by default (dryRun: true)
• Copies from the configured source folder path first, with stored imagekit.url as a fallback only when the source file cannot be found

Example:

import { migrateFolder } from '@humaan/payload-storage-imagekit'
import config from '@payload-config'
import { getPayload } from 'payload'

const payload = await getPayload({ config })

const results = await migrateFolder({
  collections: { media: true },
  dryRun: true,
  from: process.env.IMAGEKIT_FOLDER!,
  payload,
  privateKey: process.env.IMAGEKIT_PRIVATE_KEY!,
  to: process.env.IMAGEKIT_FOLDER_MIGRATION_DESTINATION!,
  urlEndpoint: process.env.IMAGEKIT_URL_ENDPOINT!,
})

console.log(results)
await payload.destroy()

migrateFolder(options) options:

• collections (required): Partial<Record<UploadCollectionSlug, true>>
• from (required): source root folder, e.g. /payload-uploads-staging
• to (required): destination root folder, e.g. /payload-uploads-production
• privateKey (required): ImageKit private API key
• urlEndpoint (required): ImageKit URL endpoint
• dryRun (optional, default true): when true, logs what would happen without writes
• payload (optional): when provided and dryRun is false, updates url + imagekit.* fields

Run a migration script:

# dry-run (default)
pnpx tsx --env-file=../.env imagekit-migration.ts

# live run
DRY_RUN=false pnpx tsx --env-file=../.env imagekit-migration.ts

Notes

• Files are uploaded under: <folder>/<collectionSlug>/<filename>.
• With clientUploads: true, the browser uploads the original file directly to ImageKit, then Payload continues its normal document save flow using the uploaded asset.
• Deletion prefers stored imagekit.fileId, with path lookup fallback.
• Admin thumbnail behavior:
  • Images: <imagekit.url>?tr=w-300,h-300
  • Videos / PDFs: <imagekit.url>/ik-thumbnail.jpg?tr=w-300,h-300

Development

pnpm dev
pnpm test:int
pnpm build