Images & Video

Overview

Media in Atomic Payload covers two things: optimized image uploads and Mux video.

Images arrive as a general-purpose upload collection that defaults to WebP with a sensible set of imageSizes, plus optional blur-data-URL placeholders for LQIP-style loading. A separate favicons collection keeps favicons out of your main image library. Video is handled by Mux: uploads stream through Mux's API and play back from Mux on the front end. Both plugins also ship child blocks, so editors can drop an image or a video straight into Atomic content.

How it works

Images

@pro-laico/images registers two upload collections and a field helper:

• Images: the general-purpose upload collection. It comes with opinionated formatOptions (WebP) and a set of imageSizes covering the breakpoints the template renders at, so every site gets the same standard sizes without reinventing them.
• Favicons: a separate collection for favicons specifically. They have different size and format requirements, and mixing them with content images would pollute the main image library.
• FaviconField: a reusable favicon-picker field config for selecting a favicon from Favicons (used in the SiteMetaData global).

Blur placeholders are opt-in. @oversightstudio/blur-data-urls is an optional peer, and the plugin does not auto-wire it: pnpm doesn't hoist the optional peer next to the package, so a require() from here would silently fail. Register blurDataUrlsPlugin yourself after imagesPlugin, passing the exported Images collection, to generate blur placeholders for uploaded images.

The plugin also ships the ImageChild block, which lets editors drop an image into Atomic blocks. It's exposed from the @pro-laico/images/blocks/imageChild subpath as the createImageBlock factory and the prebuilt Image block (not from the package root), and renders via @pro-laico/atomic/children.

Video

@pro-laico/mux-video is a thin wrapper around @oversightstudio/mux-video that:

1. Registers a local mux-video extension collection: the slug the upstream plugin attaches its fields to via extendCollection: 'mux-video'. This is where your Mux upload metadata lives.
2. Composes the upstream plugin with Atomic Payload defaults: admin thumbnail mode, a CORS origin derived from NEXT_PUBLIC_SERVER_URL, and env-driven Mux credentials.
3. Ships a VideoChild block so editors can drop a Mux video into Atomic content. Its renderer mounts the @mux/mux-video-react player and pulls playback from Mux via @pro-laico/atomic/children.

Mux requires a collection it can extend, so this package ships one in the shape every Atomic Payload site needs and normalizes the surrounding config.

Using it

In the admin, upload images to the Images collection and favicons to the Favicons collection. Pick a favicon for the site through the FaviconField in the SiteMetaData global. Upload video to the mux-video collection: uploads are pushed to Mux, and the admin list view shows a thumbnail (image, gif, or none, per the adminThumbnail option).

To place media inside Atomic content, editors drop the ImageChild and VideoChild blocks into Atomic blocks. Both render on the front end via @pro-laico/atomic/children: the image child renders an optimized image (with its blur placeholder if generated), and the video child streams playback from Mux.

Configuration

Add both plugins to your Payload config:

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

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

Use the favicon picker in a global:

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

const SiteMetaData = {
  slug: 'siteMetaData',
  fields: [
    FaviconField(),
    // ...
  ],
}

imagesPlugin(options?) accepts enabled (no-op the plugin), includeFavicons (register the bundled Favicons collection alongside Images, default true), imagesOptions (override the Images collection, where top-level keys replace but upload/access/admin are deep-merged and fields/hooks are merged, so a partial override can't silently drop the base imageSizes, mimeTypes, alt field, or access rules), and faviconsOptions (override the Favicons collection with the same deep-merge semantics).

muxVideoPlugin(options?) accepts enabled (no-op the plugin), includeCollection (register the bundled mux-video extension collection; disable if you supply your own with the same slug), collectionOptions (override the bundled collection, where top-level keys replace but access/admin are deep-merged, fields are appended, and hooks are merged per phase), adminThumbnail ('image' | 'gif' | 'none', default 'image'), uploadSettings, and initSettings.

Mux credentials and the upload origin are picked up automatically from the environment:

For the full set of options, subpaths, and exports, see the plugin references below.

Provided by

Related