Requirements: WebP Delivery & Alt Text

Two things worth pulling out as explicit, project-wide requirements rather than leaving them implicit in the Transforms reference: both are supported by the platform, and neither is automatic.

Requirement: WebP/AVIF delivery is supported, but not automatic

What’s supported: uploads accept WebP and AVIF directly (alongside PNG/JPEG/GIF; see Limits), and every delivered image can be served through Cloudflare Images’ on-the-fly format negotiation: format: "auto" picks avif → webp → jpeg based on the requesting browser’s Accept header. This is functionally equivalent to “convert to WebP with a JPEG fallback,” but better, architecturally: one stored original, transformed per request, rather than pre-generating and storing multiple format copies that can drift out of sync.

What’s not automatic: only createMediaFigureBlock() (the one ready-made component) defaults its transform to { width: 1200, height: 630, format: "auto" }. The lower-level helpers a custom component would call directly (buildImageUrl(), getMediaProps(), MediaImage, MediaFigure) have no default format at all. Omit it, and Cloudflare serves the image exactly as uploaded: no negotiation, no WebP, no AVIF, regardless of what the browser could have accepted.

Requirement (treat as a build/review checklist item, not a default): every custom Puck image component must explicitly pass transform: { format: "auto", ... } (or an equivalent) wherever it calls buildImageUrl, getMediaProps, MediaImage, or MediaFigure directly. Nothing in the plugin enforces this: a component that omits it will silently ship without WebP/AVIF delivery, and there’s no warning when that happens.

Requirement: alt text is supported, but not enforced

Rich mode (p1-media field type): alt is one of the four platform-defined metadata fields (alongside caption, credit, byline). The underlying MetadataFieldDef type does support a required flag, but the field list a project can configure locally (metadataFields on createMediaPlugin()) is explicitly documented as a fallback only, used when the live schema can’t be fetched: “not a way to add your own persisted metadata fields.” In normal operation, Pantheon’s own hosted schema (GET /media/schema, “Pantheon-defined and global for v1”) decides whether alt is required, and this project cannot override that from its own config.

Basic mode (a plain URL string field): has no alt-text mechanism at all. Confirmed directly from Pantheon’s dev guide: alt-text fields are “deliberately excluded” from the field-name patterns that trigger the picker, and getMediaProps() returns alt: "" for every basic-mode value. The documented workaround, a manually added sibling field (heroImageUrl → heroImageAlt) wired into the component’s alt prop by hand, is, in Pantheon’s own words, “not enforced by the plugin, but widely used.” Nothing stops a developer from skipping it.

Requirements:

1. Use rich mode (p1-media), not basic mode, for every image that conveys real content: basic mode has no alt-text storage to fall back on.
2. If basic mode is unavoidable (e.g. a fixed logo asset) and the image isn’t purely decorative, add the documented sibling *Alt text field by hand and pass it as the alt prop: this is a manual convention, not something the plugin automates.
3. Confirm with Pantheon whether the live media schema marks alt as required today, and whether that can be changed for this project. Until confirmed, treat “every rich-mode image has real alt text” as a manual editorial/publish-checklist item; neither the plugin nor this project’s own config currently enforces it.