@pro-laico/images

@pro-laico/images gives your Payload admin a place to upload images and favicons. The image collection converts uploads to WebP and generates a standard set of responsive sizes, a separate favicons collection keeps favicons out of your main image library, and the package ships a favicon-picker field and an image block you can use elsewhere. It's a tool the atomic-payload template and other plugins bring along, but you can add it on its own too.

Installation

pnpm add @pro-laico/images

npm install @pro-laico/images

yarn add @pro-laico/images

Setup

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

export default buildConfig({
  plugins: [imagesPlugin({ enabled: true })],
})

import { buildConfig } from 'payload'
import { imagesPlugin, Images } from '@pro-laico/images'
import { blurDataUrlsPlugin } from '@oversightstudio/blur-data-urls'

export default buildConfig({
  plugins: [
    imagesPlugin({ enabled: true }),
    blurDataUrlsPlugin({
      enabled: true,
      collections: [Images],
      blurOptions: { blur: 18, width: 32, height: 'auto' },
    }),
  ],
})

Using it in your app

The favicon field

FaviconField is a ready-made upload field that points at the Favicons collection, so you can add a favicon picker to any global or collection. It's what @pro-laico/site uses for the site's favicons; 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, a stored size, alt text, and next/image options (priority, blur, loading, and more). On the front end it renders through @pro-laico/atomic/children, which resolves the chosen image and outputs an optimized next/image.

Caching & revalidation

The package ships one cached read, getCachedImage, from the @pro-laico/images/cache subpath. Give it an image document id (and an optional size name) and it returns that upload's URL, reading Payload once instead of on every render. The image block calls it so the block looks up the chosen image by id, which keeps the rest of the page cached even when the image changes.

The Images collection revalidates the matching tag for you: saving an image refreshes its cached URL, and deleting one clears it, so the next page render serves the new URL. See Caching & revalidation for how the tags work.

Options

imagesPlugin(options?) accepts:

imagesOptions and faviconsOptions are standard Payload Partial<CollectionConfig> objects, so any collection key you pass is merged onto the built-in collection. All options at their defaults, as a working starting point:

imagesPlugin({
  enabled: true,
  includeFavicons: true,
  // imagesOptions and faviconsOptions are unset by default (no overrides merged)
})

Exports

The plugin

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

Collections & fields

import type { GlobalConfig } from 'payload'import { FaviconField } from '@pro-laico/images'// a global with light + dark favicon pickersexport const SiteMetaData: GlobalConfig = {slug: 'siteMetaData',fields: [FaviconField({ name: 'lightFavicon' }), FaviconField({ name: 'darkFavicon' })],}

The image block

import type { Block } from 'payload'import { createImageBlock } from '@pro-laico/images/blocks/imageChild'import { ClassNameField } from '@pro-laico/styles/fields/className'// the Image block with an authored class-name field prependedconst 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 map;// the renderer passes the block + pass-through props for youconst childComponents = {ImageChild,// ...other child block components}

Cache getter

import Image from 'next/image'import { getCachedImage } from '@pro-laico/images/cache'// inside the ImageChild server component, the block stores the image as a relationshipexport async function Picture({ block }) {const src = await getCachedImage(block.image?.id, block.version)if (!src) return <div className="w-full h-full bg-gray-200" />return <Image alt={block.alt ?? ''} src={src} />}

Types

Related