Media Library
P1’s built-in media handling: a Puck plugin (@pantheon-systems/p1-media) already
installed by the starter kit, not something to build. Sourced from Pantheon’s own
dev guide for the plugin, cross-checked against the installed package’s actual type
definitions.
What it is
A managed image library and picker with built-in cropping and on-the-fly transforms, served from a Pantheon-hosted CDN backed by Cloudflare Images. No infrastructure to provision: the plugin points at an already-running Pantheon media service.
Two ways a component can use it:
- Basic mode: name a field
image,imageUrl,logo,media,icon,thumbnail, or anything endingImageUrl/LogoUrl, and the plugin auto-upgrades a plain text field into a media picker. The stored value is a plain URL string; render it with the framework-agnosticbuildImageUrl(url, params)helper (works in Server Components too, no React dependency). - Rich mode: declare a field as
{ type: "p1-media" }directly. The stored value is a small object (MediaValue:assetId,versionId,url,metaSchemaVersion,alt, plus schema-driven metadata), rendered via<MediaImage>,<MediaFigure>, orgetMediaProps().
createMediaFigureBlock(), the ready-made component used by
Components Reference → Media’s Media Figure block, wraps rich mode
into a single drop-in Puck component (a captioned <figure>), configured with a
required mediaBaseUrl plus a transform object.
What’s on each page
- Transforms & Editorial Configuration: the full transform parameter table, and what an editor can/can’t configure in the picker UI.
- Requirements: WebP Delivery & Alt Text: both are supported by the platform, neither is automatic; what to actually require on every image component.
- Why the Picker Isn’t Showing: no, there’s no WordPress-style standalone library screen; the picker only lives inside a component’s field. The library is real and active in this project, confirmed by live testing, but this project also ships a second “Image” block that bypasses it entirely.
- Limits & Known Issues: upload/output caps, soft-delete-only behavior, and the one reproduced bug worth knowing about.
One real gap lives outside this section, filed under Missing Features instead of here: Bulk Management & a Library View. The library itself works (this section); there’s just no way to see or manage the whole thing at once, which is a genuine missing capability, not a nuance of how the working plugin behaves.