Media handling inside a headless CMS

What it is

Media handling inside a headless CMS is the arrangement where the CMS does not own the files. A media platform holds the assets, an app integration surfaces that library inside the CMS editor, and each entry stores a pointer to an asset rather than a copy of it. Cloudinary’s CMS integrations catalogue lists the systems it ships apps for; other media platforms publish comparable apps, and the mechanics below apply to any of them, because they are properties of the reference model rather than of one vendor.

The library lives inside the editor

The integration’s visible job is to put a media picker in the entry form. An editor writing a product page opens the media field, searches the library, and selects the asset that already exists. Without the integration, the same editor has a copy of that image on their laptop from a Slack thread, drags it into the CMS upload field, and the library now holds two of it — one that marketing approved and one that nobody knows about.

That is the point of the app: it changes the default action from upload what I have to pick what exists. Everything else on this page follows from that. The Contentful app integration is the reference example — a field type in the content model that opens the media library in a modal, with upload available inside the same dialog for the genuinely new asset — but the shape is the same in every CMS the catalogue lists.

The CMS stores a reference, not the file

What gets written into the entry is an identifier — the asset’s public ID and, in most apps, a small JSON blob of metadata the CMS can use for display and querying — not the binary. This is what keeps one asset canonical. If forty entries reference the same hero image and the image is replaced at its public ID, all forty pick up the change on next delivery. Nobody edits forty entries, and no build step re-syncs a copy.

It also means the CMS’s own asset store stays small and its content export stays portable: an entry export contains identifiers, and the media platform holds the bytes. The failure mode this prevents is the one every team eventually meets when the CMS does hold the files — the same logo at eleven paths, three of them the old logo, and no way to tell from the CMS which is current.

The cost is a dependency. The entry is now incomplete without the media platform, so an outage or a broken plugin surfaces as missing images across the site rather than in one place. Diagnosing a CMS media plugin that stops delivering is a separate page because that dependency is real and worth understanding before you take it on.

Transformation happens at delivery, not at storage

Because the CMS holds an identifier, it does not need to hold a rendition. The front end constructs the delivery URL — width, crop, format, quality — at render time, from the identifier plus whatever the layout needs at that spot. The same asset is a 400-pixel card thumbnail on the listing page and a full-bleed 2,000-pixel hero on the article, and the CMS knows nothing about either.

The contrast is a CMS that stores a sized URL. That URL bakes a layout decision — this image is 1,200 wide, cropped square — into the content record. When the design changes, the content is wrong, and the fix is a content migration rather than a template edit. It is the same category of mistake as putting a colour hex code in a body field: a presentation concern has leaked into the data layer, and the leak is invisible until the redesign.

The practical rule that falls out of this: the value stored in the CMS field should be the smallest thing that identifies the asset. If the integration offers to store a derived URL for convenience, prefer the raw identifier and derive at the edge. Cloudinary’s plans meter transformations in credits — 1,000 image or video transformations per credit on the ladder as of 2026-08-18 — so delivery-time transformation is a metered operation, not a free one, and a site with many distinct renditions per asset should know that going in.

Folder mode decides what the CMS can see

The integration exposes either the whole library or a scoped subtree of it, and which of those you get is set by the product environment’s folder mode. The details of what each mode permits, and which integrations support which, are in the folder modes in integrations reference; Folder modes and what a no-code integration is allowed to see walks through the consequences for editors.

The decision is cheap on an empty library and expensive on a full one. Choosing scope before editors have filed anything means the folder structure is designed around who needs to see what — brand assets in one subtree, per-market campaign material in another, the CMS pointed at the subset editors should be picking from. Choosing it after a thousand assets have been filed by habit means either reorganising the tree, which touches every asset’s path, or living with a picker that shows editors everything and relies on search to make it usable. Most teams that skip this step end up in the second situation, which is where the next point starts to bite.

The integration is only as good as the editor’s search

An editor picks an existing asset only if they can find it faster than they can re-upload their local copy. That is a search problem, and search over media is a metadata problem — filename and upload date are not enough once the library passes a few hundred items. So the thing that decides whether the integration is actually used, as opposed to installed, is the metadata schema: what fields exist, whether they are structured or free text, and whether they are populated.

Structured metadata — a controlled campaign field, a product reference, a usage-rights enum — is what makes the in-editor picker filterable rather than a scroll. Tags and alt text help, and alt-text generation inside a media automation flow covers filling one of those fields without asking editors to type it. But the schema has to be designed, and the existing library has to be back-filled against it, before the picker becomes the path of least resistance. Exporting asset metadata for review outside the platform is the usual first step in finding out how sparse the current library actually is.

The symptom of skipping this is not an error. It is a library that grows duplicates at the same rate it did before the integration, because editors tried search twice, failed, and went back to uploading.

What to check next

A reader setting this up will want three things from the documentation: which CMS apps exist and what each stores in the entry field, what the product environment’s folder mode currently is and whether it can still be changed cheaply, and what structured metadata fields the media platform supports for the picker to filter on. All three are decisions about the data, not the code, and all three are easier to make before the first editor uploads their first duplicate.