@pro-laico/images

@pro-laico/images turns a Payload upload collection into an on-demand image pipeline. An upload stores just the original; every rendered size is generated the first time a page asks for it (resized and cropped to a focal point you set in the admin), then cached so it is only ever built once. It also ships a responsive image component, a built-in low-res placeholder, a separate favicons collection with a reusable picker field, and an image block for Atomic content.

The core pieces (the Images collection, the transform endpoint, <ResponsiveImage>, the focal-point UI, and the placeholder) need only @pro-laico/core, so the package works in any Payload + Next.js app. The atomic-payload template wires it up for you, but you can add it on its own. There's a minimal standalone demo in examples/images-only.

Installation

pnpm add @pro-laico/images

npm install @pro-laico/images

yarn add @pro-laico/images

Setup

import { buildConfig } from 'payload'
import sharp from 'sharp'
import { imagesPlugin } from '@pro-laico/images'

const serverURL = process.env.NEXT_PUBLIC_SERVER_URL || 'http://localhost:3000'

export default buildConfig({
  sharp, // required: the transform endpoint resizes/crops with Sharp
  serverURL,
  cors: [serverURL],
  plugins: [imagesPlugin()],
})

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  serverExternalPackages: ['sharp'],
}

export default nextConfig

pnpm payload generate:importmap

Using it in your app

Rendering images with <ResponsiveImage>

<ResponsiveImage> is the front-end surface. It emits a plain <img> whose srcset points at the transform endpoint, so the browser downloads the one size that fits where the image renders. It is not next/image, and it runs in both server and client trees. Import it from the @pro-laico/images/components/image subpath:

import { getPayload } from 'payload'
import config from '@payload-config'
import { ResponsiveImage } from '@pro-laico/images/components/image'

// A server component that loads an image and renders it responsively.
export async function Hero({ id }: { id: string }) {
  const payload = await getPayload({ config })
  const image = await payload.findByID({ collection: 'images', id, depth: 0 })

  return <ResponsiveImage image={image} aspectRatio="16:9" sizes="(max-width: 768px) 100vw, 50vw" />
}

Pass the populated document (not just an id) when you can: that fills in the intrinsic width/height (so the layout doesn't shift), the alt fallback, and the cache-busting version token. (The placeholder is derived from the id, so it works either way.) The endpoint reads the focal point from the document and crops server-side, so the component never needs it.

The srcset granularity is a prop on <ResponsiveImage>, set where you render the image (it isn't a plugin option). Pass pixelStep (default 50px) to change the step; raise it to emit fewer widths, so the browser has fewer sizes to choose from and the endpoint generates fewer variants. maxEntries (default 8) caps how many entries before the step coarsens.

// fewer, wider steps for this image
<ResponsiveImage image={image} aspectRatio="16:9" sizes="100vw" pixelStep={100} />

Full-bleed / cover fill

By default <ResponsiveImage> is an aspect-ratio box: its <img> is width:100%; height:auto, so the image drives the box's height. For a full-bleed hero, a carousel slide, or any element that sets its own height, pass fill. The wrapper becomes position:absolute; inset:0; size:100% and the <img> renders object-fit:<fit> with no aspect-ratio, covering the (positioned) parent — while still painting the LQIP placeholder. This replaces the bespoke <img className="absolute inset-0 size-full object-cover"> pattern, which bypasses the placeholder/srcset wiring.

// the parent owns the height; the image covers it
<div className="relative h-screen">
  <ResponsiveImage image={image} fill sizes="100vw" />
</div>

fill ignores aspectRatio (the image is served at its natural ratio and CSS object-fit covers the box). The parent must establish a positioning context (relative / absolute) and a height.

The favicon field

FaviconField is a ready-made upload field that targets the Favicons collection, so you can add a favicon picker to any global or collection. It's what @pro-laico/site uses; add it to your own config the same way:

import { FaviconField } from '@pro-laico/images'

const SiteMetaData = {
  slug: 'siteMetaData',
  fields: [FaviconField({ name: 'lightFavicon' }), FaviconField({ name: 'darkFavicon' })],
}

Pass a name (and anything else a Payload upload field accepts) to mount more than one picker. The field always targets the favicons collection, so an override can't accidentally re-point it.

The image block

The package ships an Image block (slug ImageChild) that lets editors drop an image into Atomic content. It isn't registered by imagesPlugin; it's one of the default child blocks the Atomic renderer wires up, so in most setups you get it for free. To register it in your own block list, import it from the @pro-laico/images/blocks/imageChild subpath:

import { createImageBlock, Image } from '@pro-laico/images/blocks/imageChild'

// The prebuilt block:
const blocks = [Image]

// …or build your own, prepending/appending fields (e.g. a class-name field):
const customImageBlock = createImageBlock({ prependFields: [], appendFields: [] })

The block lets the editor choose the image and per-placement display options (alt, aspect ratio, sizes, quality, fit, priority or lazy loading, and whether to show the placeholder). On the front end it renders through @pro-laico/atomic/children as a <ResponsiveImage>.

Caching & revalidation

There are three caches working together, and the plugin keeps them honest:

• The variant cache (generatedImages). The first request for a size generates it and stores it; later requests stream the stored copy. When you replace the file or move the focal point, the change/delete hooks purge that image's stale variants so they regenerate. The Purge variants button (and POST /api/img/purge/:id) clears them on demand.
• The browser/CDN cache. Transform responses are immutable, and every URL carries a v token derived from the source's filename and focal point. Replacing the file or moving the focal point yields a new URL, so already-cached responses refetch; a metadata-only edit (like alt) leaves them untouched.
• The Next.js data cache. getCachedImage (from @pro-laico/images/cache) reads an upload's URL once per id instead of querying Payload on every render, and the Images collection revalidates the matching tag on save and delete.

See Caching & revalidation for how the tags work.

Security & abuse limits

The transform endpoint is public-facing, so it's bounded on several fronts:

• Access control. Source reads run with the collection's access rules (not overrideAccess). A source you can't read returns 404, and a non-public source is served with a private cache header and no shared CDN caching — only public images get immutable + CDN-Cache-Control. The purge endpoint (POST /api/img/purge/:id) requires a logged-in user who can read that source, so it can't be used to force costly regeneration of images they can't even see.
• Bounded variant space (DoS). Requested dimensions snap to the dimensionStep grid and quality buckets to a small set, both clamped to maxDimension — so a caller can't spin up unbounded distinct variants with w=1,2,3,…. Output never upscales past the source.
• Bounded work per request. maxInputPixels caps how many pixels Sharp will decode (a decompression-bomb guard that also caps memory — ~400 MB at 100 MP), and the transform concurrency gate (maxConcurrency / sharpConcurrency) keeps a cold page that requests many sizes at once from saturating CPU/memory.
• SSRF + path traversal on source reads. Local reads are confined to the collection's staticDir — a resolved path that escapes the directory is rejected. Cloud/relative reads self-fetch the source over HTTP with redirects disabled, a 15 s timeout, and a 64 MB body cap, and refuse loopback / private / link-local hosts (blocking cloud metadata endpoints and internal services) while still allowing your configured NEXT_PUBLIC_SERVER_URL origin.
• Upload validation. Both collections accept only image/png, image/jpeg, image/webp, and image/avif.

Options

imagesPlugin(options?) accepts:

All options at their defaults, as a working starting point:

imagesPlugin({
  enabled: true,
  includeFavicons: true,
  // imagesOptions / faviconsOptions / generatedImagesOptions: unset (no overrides merged)
  pregenerateSizes: false, // store only the original; every size is on demand
  focalUI: true,
  previewRatios: ['16:9', '9:16', '1:1', '4:3', '3:2', '21:9'],
  transform: {
    sourceSlug: 'images',
    variantSlug: 'generatedImages',
    cdnCacheControl: true,
    maxDimension: 4096,
    defaultQuality: 75,
    qualityRange: [40, 95],
    defaultFormat: 'auto',
    formats: ['auto', 'avif', 'webp', 'jpeg', 'png'],
    preferAvif: false, // auto serves WebP; set true to prefer AVIF in fmt=auto
    dimensionStep: 50, // snap w/h to a 50px grid (anti-DoS); <= 1 disables
    maxInputPixels: 100_000_000, // ~100MP decode cap (bomb + memory guard)
    // maxConcurrency: cpus - 1, // cross-image transform gate
    // sharpConcurrency: 1, // per-image libvips threads (0 = CPU cores)
  },
})

Environment variables

Exports

The plugin

import { buildConfig } from 'payload'import sharp from 'sharp'import { imagesPlugin } from '@pro-laico/images'export default buildConfig({sharp,plugins: [imagesPlugin()],})

Fields & admin components

import type { GlobalConfig } from 'payload'import { FaviconField } from '@pro-laico/images'export const SiteMetaData: GlobalConfig = {slug: 'siteMetaData',fields: [FaviconField({ name: 'lightFavicon' }), FaviconField({ name: 'darkFavicon' })],}

Frontend components

import { ResponsiveImage } from '@pro-laico/images/components/image'// inside a server or client component, with a populated image doc<ResponsiveImage image={image} aspectRatio="16:9" sizes="(max-width: 768px) 100vw, 50vw" />

import { getImageUrl } from '@pro-laico/images/components/buildSrcset'const ogUrl = getImageUrl(image, { width: 1200, aspectRatio: '1.91:1', baseUrl: process.env.NEXT_PUBLIC_SERVER_URL })

import { buildSrcset, deriveVersion } from '@pro-laico/images/components/buildSrcset'const { srcset, src } = buildSrcset(String(image.id), {aspectRatio: '16:9',sourceWidth: image.width,version: deriveVersion(image),})

import { buildVariantUrl, deriveVersion } from '@pro-laico/images/components/buildSrcset'const ogUrl = buildVariantUrl(String(image.id), 1200, {aspectRatio: '1.91:1',baseUrl: process.env.NEXT_PUBLIC_SERVER_URL,version: deriveVersion(image),})

import { deriveVersion } from '@pro-laico/images/components/buildSrcset'const v = deriveVersion(image) // pass to buildSrcset / buildVariantUrl

The image block

import type { Block } from 'payload'import { createImageBlock } from '@pro-laico/images/blocks/imageChild'import { ClassNameField } from '@pro-laico/styles/fields/className'const imageBlock: Block = createImageBlock({ prependFields: [ClassNameField({ namePrefix: 'image' })] })

import { ImageChild } from '@pro-laico/images/blocks/imageChild/component'// register it for the ImageChild slug in your Atomic children mapconst childComponents = { ImageChild }

Cache getter

import { getCachedImage } from '@pro-laico/images/cache'const src = await getCachedImage(block.image?.id, block.version)

Schema types

Related