Payload Image Cropper

Setup

Local Filesystem Storage

Use this when your media collection stores files on disk (default Payload upload behavior).

  1. 1

    Configure your media collection

    Set staticDir on the upload collection:

    typescript
    {
  slug: 'media',
  upload: {
    staticDir: 'public/media',
  },
  fields: [],
}
  2. 2

    Add the plugin with matching mediaDir

    mediaDir must be an absolute path pointing to the same directory as staticDir.

    typescript
    import path from 'path'
import { cropImagePlugin } from 'payload-plugin-image-cropper'

cropImagePlugin({
  mediaCollectionSlug: 'media',
  mediaDir: path.join(process.cwd(), 'public/media'),
})
  3. 3

    Serve crop files

    Generated crops are written to the same directory as source media. If staticDir is public/media, crop URLs look like /media/photo-crop-desktop-....webp and are served like any other upload.

  4. 4

    Add crop fields

    See Single-Size Crops or Multi-Size Crops for field configuration.

Important

Always use process.cwd() for mediaDir, not __dirname or import.meta.url. Payload resolves staticDir relative to the working directory, not the config file location.